Roadmap to v0.1.0

This issue tracks the work required to take `codejson-crosswalk` from its current state to an official v1 release.

## Phase 1: Core Correctness

- [x] **Define and export the public API in `src/index.ts`**
- Currently `src/index.ts` is an empty stub. Decide which functions and types are part of the public surface, and export them cleanly so downstream consumers can import from the package root.
- ***Acceptance:*** A TypeScript project can `import { fromCodemetaToCodejson, fromCodejsonToCodemeta, MappingEntry } from "codejson-crosswalk"` with full type inference.

- [x] **Remove hardcoded test scripts from `handler.ts`**
- The bottom of `handler.ts` reads real files and logs results at import time. Move this into an example script or a test, leaving `handler.ts` as pure library code.
- ***Acceptance:*** Importing anything from `handler.ts` produces no side effects, no console output, and no file reads.

- [x] **Set up `bun test` and write unit tests for the engine**
- Add test coverage for `getNestedValue`, `setNestedValue`, and `convert`, including edge cases like missing paths, nested writes that merge into existing objects, and target-only defaults.
- ***Acceptance:*** `bun test` runs successfully, each helper has unit tests covering the happy path and at least two failure modes, and coverage on these three files is at least 90%.

- [x] **Add round-trip integration tests for codemeta ↔ code.json**
- Convert real sample files in each direction and assert on the resulting output shape. Include at least one round-trip test that documents what information is preserved and what is lost.
- ***Acceptance:*** Integration tests exist for both directions, run as part of `bun test`, and the lossy fields are explicitly asserted rather than silently dropped.

- [x] **Create a `fixtures/` directory with representative sample files**
- Build a small library of valid input files covering minimal, fully-populated, and edge-case shapes (multi-license, multi-author, missing optional fields). These serve both tests and documentation.
- ***Acceptance:*** At least three codemeta fixtures and three code.json fixtures exist under `fixtures/`, each with a short comment or companion README explaining what it represents.

## Phase 3: Usability

- [x] **Generate API documentation with TypeDoc**
- Set up TypeDoc to generate reference documentation from the exported functions and types. Add JSDoc comments to every public export.
- ***Acceptance:*** Running the docs command produces an HTML site covering every public export, and the generated docs are published (GitHub Pages or committed to `docs/`).

- [x] **Add a CLI entry point**
- Expose a command-line interface so users can convert files without writing TypeScript. Support reading from stdin or a file path and writing to stdout or a file.
- ***Acceptance:*** After `npm install -g codejson-crosswalk`, the command `codejson-crosswalk input.json --to codejson` produces a valid converted file, and `--help` describes all flags.

- [x] **Create an `examples/` directory with runnable usage scripts**
- Provide minimal, focused example scripts for the common use cases: converting a single file, batch-converting a directory, and converting with output validation.
- ***Acceptance:*** At least three runnable examples exist under `examples/`, each with a short README explaining what it demonstrates and how to run it.

- [x] **Audit and improve error messages**
- Walk through every failure mode — malformed input, missing files, failed validation, transform errors — and make sure each produces a message that identifies what went wrong and where.
- ***Acceptance:*** A test suite for error paths exists, and each tested error includes both the failure type and a location or field reference in the message.

## Phase 4: Maintainability

- [x] **Set up GitHub Actions for CI**
- Add a workflow that runs install, test, lint, and coverage on every PR and push to main. Fail the build if tests fail or coverage drops below a threshold.
- ***Acceptance:*** A PR with a failing test or a lint violation is blocked by a red CI check, and the coverage threshold is documented in the workflow file.

- [x] **Add ESLint and Prettier**
- Adopt a shared preset (e.g. `@typescript-eslint/recommended` plus Prettier) and wire both into the CI workflow. No hand-rolled style debates.
- ***Acceptance:*** `bun run lint` and `bun run format` both exist and succeed on the codebase, and the CI workflow runs both on every PR.

## Phase 5: Release

- [x] **Finalize package.json fields for publication**
- Set `main`, `module`, `types`, `exports`, and `engines` correctly so that downstream consumers can import the package cleanly in both ESM and CommonJS contexts and know which runtimes are supported.
- ***Acceptance:*** A test consumer project can install the packaged tarball (`npm pack` output) and import both types and runtime code without configuration.

- [x] **Create a CHANGELOG and adopt semver**
- Add a `CHANGELOG.md` following the Keep a Changelog convention, document the v1.0.0 release, and update contributing docs to require changelog entries in future PRs.
- ***Acceptance:*** `CHANGELOG.md` exists with a v1.0.0 entry, and `CONTRIBUTING.md` instructs contributors to update it.

- [ ] **Set up a release workflow to publish to npm on tags**
- Add a GitHub Actions workflow that publishes to npm when a version tag is pushed. Configure the npm token as a repository secret.
- ***Acceptance:*** Pushing a tag like `v0.0.1-test` to a test branch triggers a successful (dry-run or scoped) publish, proving the workflow works before the real release.

- [ ] **Cut and publish v1.0.0**
- Run through a pre-release checklist (tests green, docs current, changelog updated, version bumped, compliance files in place), tag the release, and publish.
- ***Acceptance:*** `codejson-crosswalk@1.0.0` is installable from npm, and a GitHub release exists with release notes mirroring the changelog entry.