feat: compatibility contract, trace field, git-install ergonomics

[Yashasvi2229]

What

Three changes that round out the public-API work from #44:

• COMPATIBILITY.md at the repo root — written contract for embedders.
  Defines the public surface (everything re-exported from src/index.ts),
  semver interpretation (additive minors, breaking majors), the "soft" exports
  whose names are stable but contents aren't (DEFAULT_SCAFFOLD_PATTERNS,
  DEFAULT_HEARTBEAT_PATTERNS), scaffold-directory ownership (which paths
  inside .mex/ mex owns vs. reserves for embedders, including .mex/traces/
  and .mex/failures/), the CLI-flag policy, and the deprecation window.

• EventEntry.trace?: string — optional field on event-log entries,
  pointing at a long-form trace document (free-form string, typically a path
  under .mex/traces/). Wired through appendEvent (accepts trace in
  LogOpts) and readEvents (preserved when present, ignored when absent —
  so old log lines parse unchanged). Lets embedders that need richer context
  per event link to it without forking the event format.

• "prepare": "npm run build" in package.json — so
  npm install github:<fork>/mex builds dist/ automatically inside the
  consumer's node_modules. Without this, git-URL installs resolve but ship
  no dist/, and the consumer has to cd node_modules/mex-agent && npm run build
  manually. COMPATIBILITY.md is also added to the files array so it ships
  with published packages.

Also re-adds the COMPATIBILITY.md JSDoc references in src/index.ts and
test/public-api.test.ts that were stripped during the review of #44 — the
doc didn't exist then; now it does.

Why

• The compatibility contract turns mex-agent into something embedders can
  depend on without pinning exact versions or guessing at stability. The
  scaffold-ownership section in particular prevents future namespace
  collisions between mex and tools building on top of it.
• The trace field is the minimum data-model change needed for tools that
  capture longer-form decision context to coexist with mex's event log.
  Strictly additive — trace is optional, defaults to absent, and old log
  lines round-trip unchanged.
• prepare removes the manual npm run build step for anyone installing
  from a fork branch, which is the workflow embedders use during development
  before a release is on npm.

Type of change

• Bug fix
• New feature
• Refactor
• Docs
• CI/Tooling

How to test

1. npm run typecheck — clean.
2. npm test — 155 tests total; 2 new trace round-trip tests in
   test/public-api.test.ts pass. Pre-existing Windows path-separator
   failures in test/heartbeat.test.ts:38 and test/scanner.test.ts:56 are
   unrelated to this PR (still failing on main, pass on Linux CI).
3. npm run build — dist/index.d.ts grows slightly to include the new
   trace?: string field on EventEntry and LogOpts.
4. Round-trip check: append an event with appendEvent(config, "msg", { kind: "decision", trace: ".mex/traces/foo.md" }),
   then readEvents(config) — the trace string should come back. Append
   another event without trace; reading it back, trace should be
   undefined.

Checklist

• Tests pass (npm test) — 153 green; 2 pre-existing Windows failures
  unrelated.
• No breaking changes — all additions are additive: new file, new optional
  field, new script entry, new docs.
• Tested locally — typecheck, full test suite, and build all verified on
  Windows.

[theDakshJaitly]

Mostly looks good — one real issue and two things worth knowing.

Please fix before merge

COMPATIBILITY.md lists LogOpts as a public type, but it's not actually exported from src/index.ts. The doc at line 23 includes `LogOpts` in the type surface, and the JSDoc for the new `trace` field references it, but `src/index.ts` only exports `EventEntry` and `EventKind` from `events.js`. The smoke test doesn't import `LogOpts` either, so the contract this PR documents drifts from the code on day one.

Fix one of:

• Add `LogOpts` to `src/index.ts` exports and to the `test/public-api.test.ts` type imports (preferred — `appendEvent` callers benefit from the typed opts shape), or
• Drop `LogOpts` from `COMPATIBILITY.md`.

Things worth knowing (not blockers)

1. prepare script runs on every local npm install in this repo, not just consumer git-URL installs. A broken build will now block local installs and npm publish. The trade-off is fine — just flagging it for future debugging when an install fails for a non-obvious reason.

2. npm publish will now auto-build because prepare runs in the pack step. So the publish flow becomes a single npm publish — no separate npm run build needed. Worth noting in any release docs you keep.

What's good

• EventEntry.trace is genuinely additive — readEvents preserves it when present, ignores it when absent, so old decisions.jsonl lines round-trip unchanged. The two new tests cover both cases.
• COMPATIBILITY.md is well-scoped: hard vs. "soft" exports, embedder/mex boundary inside .mex/, explicit .mex/traces/ and .mex/failures/ carve-outs, honest about CLI-flag best-effort policy.
• prepare script genuinely fixes the git-URL install workflow that was broken before.

All 155 tests pass locally (153 prior + 2 new). CI green on Node 20/22.

[theDakshJaitly]

LGTM — LogOpts mismatch fixed, and binding the test opts as LogOpts means the contract drift can't recur silently. Approving and merging.