diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..8948cef
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,146 @@
+# AGENTS.md
+
+Guidance for contributors and coding agents working in this repository.
+
+## Quick Start
+
+1. Confirm the request scope and avoid unrelated changes.
+2. Read `README.md` and the relevant files in `src/` before editing.
+3. Make the smallest viable change; do not restructure folders or rename files unless requested.
+4. Run only the checks needed for the change (`npm run test` and/or `npm run build`).
+5. Summarize what changed, why it changed, and any follow-up work.
+
+> When in doubt: prefer existing project patterns over introducing new abstractions.
+
+## Project Overview
+
+OpenCite is a Vite + React single-page app that helps users generate two metadata files from one form:
+- `CITATION.cff`
+- `.zenodo.json`
+
+OpenCite is browser-based and deployed through GitHub Pages
+(`https://imageomics.github.io/OpenCite/`).
+
+Primary goals:
+- Keep metadata exports valid and stable.
+- Keep the form workflow predictable and easy to edit.
+- Preserve browser-first behavior (no Node-only runtime assumptions in app code).
+- Maintain metadata quality through import, validation, comparison, and health
+  feedback workflows.
+
+## Tech Stack
+
+- React 18
+- Vite 5
+- Plain JavaScript (ES modules)
+- Node test runner (`node --test`) for utility-level tests
+
+## Commands
+
+Run from repo root:
+
+```bash
+npm install
+npm run dev
+npm run build
+npm run test
+npm run validate:metadata
+npm run preview
+```
+
+## Imageomics Collaboration Expectations
+
+Contributions should align with Imageomics principles of:
+
+- Transparency
+- Accountability
+- Collaboration
+- Safety
+
+Expected behavior:
+
+- Communicate clearly and respectfully.
+- Keep changes focused and explain assumptions and tradeoffs.
+- Provide enough context for others to reproduce and review results.
+
+## Key File Map
+
+- `README.md`
+  - Contributor-facing run instructions plus release/citation metadata workflow guidance.
+- `CONTRIBUTING.md`
+  - Project contribution workflow, branch/PR conventions, and review expectations.
+- `src/App.jsx`
+  - Main app orchestration: form state, previews, export flow, import flow.
+- `src/components/MetadataForm.jsx`
+  - Form UI rendering and field-level interactions.
+- `src/validation/validation.js`
+  - Input normalization and validation checks.
+- `src/metadata/normalizeMetadata.js`
+  - Canonical metadata shaping before export.
+- `src/services/citation.js`
+  - `CITATION.cff` serialization.
+- `src/services/zenodo.js`
+  - `.zenodo.json` serialization.
+- `src/services/githubImporter.js`
+  - GitHub import pipeline; returns `{ metadata, warnings, errors, review, healthScan, comparisons }`.
+- `src/services/github.js`
+  - Legacy re-export surface for GitHub import API compatibility.
+- `src/services/orcidSearch.js`
+  - ORCID candidate lookup and scoring helpers.
+- `src/utils/*.js`
+  - Parsing/normalization helpers for authors, grants, keywords, references, ORCID.
+
+## Repository Conventions
+
+1. Use explicit `.js` and `.jsx` import specifiers in source files.
+2. Canonical Zenodo export filename is `.zenodo.json` (with leading dot).
+   - App export uses a direct browser download path for `.zenodo.json`; verify
+     filename behavior in your browser environment when validating releases.
+3. For browser/Vite runtime configuration, prefer `import.meta.env` over `process.env`.
+4. Preserve `CITATION.cff` export behavior, including identifiers for release URL and tag tree/commit URL when applicable.
+5. Keep changes focused and minimal; avoid unrelated refactors.
+6. Do not restructure folders, rename files, or alter public service APIs unless explicitly requested.
+
+## Workflow Expectations
+
+1. Read relevant files before editing.
+2. Make the smallest viable change that satisfies the request.
+3. If the request is documentation-only, update existing docs first (`README.md`, `CONTRIBUTING.md`, `AGENTS.md`) before creating new docs.
+4. Run targeted checks:
+   - `npm run test` for logic changes.
+   - `npm run build` for UI/export pipeline changes.
+5. If behavior changes user output, verify both generated files still render and download correctly.
+6. Summarize exactly what changed and why.
+
+## Scope Boundaries
+
+- Do not perform broad formatting passes or cleanup-only changes outside the requested area.
+- Do not replace existing workflows with new patterns when a localized fix is sufficient.
+- Prefer updating existing documentation sections over creating new docs files.
+
+## Validation and Data Rules
+
+- Required metadata fields are validated before export.
+- ORCID values must pass format/checksum validation when provided.
+- Grant IDs use: `<funder-code>::<grant-number>`.
+- Publication date should be a real `YYYY-MM-DD` date.
+- References may be plain-text lines or structured blocks; do not silently drop entries.
+
+## UI and Interaction Expectations
+
+- Keep export notices actionable and specific.
+- Do not remove confirmation safeguards that prevent accidental low-quality exports.
+- Preserve author ordering tools and ORCID suggestion flow.
+
+## Backward Compatibility
+
+- Do not break public function names used across `src/services/*`.
+- Keep `src/services/github.js` compatibility exports intact unless migration is requested.
+- Avoid changing file names used in download/export without explicit request.
+
+## Definition of Done for Agent Changes
+
+- Code compiles (`npm run build`).
+- Tests pass (`npm run test`) or test impact is clearly documented.
+- No unintended changes to export filenames or core metadata shape.
+- Any new assumptions are documented in README or inline code comments where needed.
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
new file mode 100644
index 0000000..73e012a
--- /dev/null
+++ b/CODE_OF_CONDUCT.md
@@ -0,0 +1,148 @@
+# OpenCite Code of Conduct
+
+OpenCite aligns with the Imageomics community Code of Conduct. All community
+members and contributors are expected to engage respectfully, responsibly, and
+constructively in project spaces.
+
+## Scope
+
+This Code of Conduct applies to all OpenCite project spaces, including:
+
+- GitHub issues, discussions, pull requests, and code reviews.
+- Documentation, examples, and repository contributions.
+- Project-related communication channels and community interactions.
+
+All contributors, maintainers, reviewers, and users participating in these
+spaces are expected to follow these guidelines.
+
+## Principles of Engagement
+
+- Listen to understand.
+- Speak to be understood, and recognize that everyone is learning.
+- Embrace "Yes and..." by focusing on possibilities and being inclusive of ideas.
+- Take space and make space to encourage balanced participation.
+- Beware of blind spots and recognize differences in experience and perspective.
+- Respect time and boundaries during discussions.
+- Care for each other as members of the community.
+
+## Repository Contributor Expectations
+
+In repository spaces, contributors are expected to:
+
+- Demonstrate empathy and respect in discussions, reviews, and decisions.
+- Give and receive constructive feedback focused on ideas, code, and outcomes.
+- Take responsibility for mistakes, address impacts, and help resolve issues.
+- Use welcoming and inclusive language.
+- Avoid harassment, personal attacks, discriminatory language, and disruptive
+  behavior.
+
+## Pull Request and Review Guidelines
+
+Contributors should:
+
+- Provide clear context about changes, design decisions, and known limitations.
+- Keep pull requests focused and manageable when possible.
+- Respond to review feedback thoughtfully and respectfully.
+- Distinguish technical disagreement from personal disagreement.
+- Review contributions based on technical merit, project goals, and community
+  standards.
+- Recognize that feedback is intended to improve the project rather than
+  criticize individuals.
+
+## Issues and Discussions
+
+Contributors should:
+
+- Provide sufficient context when creating issues or discussions.
+- Share reproducible examples when reporting bugs.
+- Avoid dismissive, hostile, or unconstructive responses.
+- Help maintain discussions that are respectful, focused, and useful for
+  improving the project.
+
+## AI-Assisted Contributions
+
+AI tools may be used during development, but contributors are responsible for
+reviewing and understanding all submitted changes.
+
+Contributors remain responsible for ensuring correctness, licensing compliance,
+and appropriate handling of confidential, private, or restricted information.
+
+When using AI-assisted tools:
+
+- Verify generated code before submitting a pull request.
+- Ensure contributions follow project licensing and attribution requirements.
+- Do not include confidential, private, or restricted information in AI tools.
+- Treat AI-generated suggestions as reviewable input rather than automatically
+  trusted output.
+
+Contributors should disclose substantial AI-assisted contributions when they
+meaningfully influence the design, implementation, documentation, or review
+process of a change.
+
+## Learning and Collaboration
+
+OpenCite welcomes contributors with different levels of experience.
+Contributors are encouraged to:
+
+- Ask questions when clarification is needed.
+- Share knowledge and provide constructive guidance.
+- Recognize that mistakes are part of the development process.
+
+## Community Values
+
+### Transparency
+
+Be clear about assumptions, uncertainty, and limits. Share information and
+processes openly whenever possible.
+
+### Accountability
+
+Take responsibility for outcomes and ensure methods align with intended use.
+
+### Collaboration
+
+Build welcoming environments, value diverse perspectives, and work together
+creatively. Respect the goals of open science, reproducibility, and responsible
+software development.
+
+### Safety
+
+Practice ethical and responsible approaches, address issues, and promote good
+governance.
+
+## Maintainer Responsibilities
+
+Project maintainers are responsible for:
+
+- Helping maintain a welcoming and respectful environment.
+- Reviewing contributions fairly and consistently.
+- Addressing concerns and reports appropriately.
+- Communicating decisions and expectations clearly.
+- Focusing discussions on technical decisions, tradeoffs, and project goals
+  rather than individuals.
+- Approaching discussions with good intent while remaining open to correcting
+  misunderstandings.
+
+## Enforcement and Reporting
+
+Misconduct is prohibited in all project spaces and interactions.
+
+Violations may result in removal from the project and further action as
+appropriate.
+
+If you experience or witness concerning behavior, report it by contacting
+project maintainers through the repository support channels. Security concerns
+should be reported according to the process described in SECURITY.md.
+
+Reports will be reviewed promptly, and privacy will be protected as much as
+possible.
+
+## Attribution
+
+This Code of Conduct is adapted from the Imageomics Guide / Collaborative
+Distributed Science Guide developed by the Imageomics Institute and ABC Global
+Center. The original community principles were adapted to address repository
+contributions, code review, and software development practices.
+
+Source:
+https://imageomics.github.io/Imageomics-guide/CODE_OF_CONDUCT/
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..9542003
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,159 @@
+# Contributing to OpenCite
+
+Thank you for contributing to OpenCite.
+
+This document defines how to contribute safely and consistently to this repository.
+It aligns OpenCite contribution practices with Imageomics Institute collaborative
+development guidance.
+
+## Scope
+
+- Keep pull requests focused on one feature or bug fix.
+- Avoid unrelated refactors and formatting-only changes.
+- Preserve existing export behavior for `CITATION.cff` and `.zenodo.json` unless your change is explicitly about metadata output.
+
+## Development Setup
+
+1. Fork the repository and create a branch from `main`.
+2. Install dependencies:
+
+```bash
+npm install
+```
+
+3. Run the app locally:
+
+```bash
+npm run dev
+```
+
+## Branching and Commits
+
+- Do not work directly on `main`.
+- Use descriptive branch names, for example:
+  - `feature/issue-123/grant-autofill`
+  - `bugfix/issue-88/semver-validation`
+  - `docs/issue-40/readme-contributing`
+- Use clear commit messages that explain the change and intent.
+
+## Pull Request Checklist
+
+Before opening a pull request:
+
+1. Confirm the change matches the issue/task scope.
+2. Run checks:
+
+```bash
+npm run test
+npm run build
+npm run validate:metadata
+```
+
+`npm run validate:metadata` runs `CITATION.cff` checks and validates
+`.zenodo.json` with the pinned Zenodraft CLI version used by CI.
+
+3. Complete this checklist before submitting:
+
+**Code changes:**
+
+- [ ] Change is focused on one feature, fix, or documentation update.
+- [ ] Tests were added or updated when applicable.
+- [ ] Existing functionality was not unintentionally broken.
+- [ ] `npm test` passes.
+- [ ] `npm run build` passes.
+
+**Metadata and citation changes:**
+
+- [ ] `CITATION.cff` remains valid.
+- [ ] `.zenodo.json` remains valid.
+- [ ] Citation metadata fields are consistent.
+- [ ] Author and contributor information is reviewed.
+- [ ] Version and release information are consistent.
+
+**Documentation:**
+
+- [ ] User-facing changes are documented.
+- [ ] Repository guidance is updated if contributor workflows change.
+- [ ] Links to related Imageomics or Collaborative Distributed Science resources are updated when relevant.
+
+**Release readiness:**
+
+- [ ] Version follows semantic versioning.
+- [ ] Release notes or changelog information is prepared when applicable.
+- [ ] GitHub release metadata, `CITATION.cff`, and Zenodo metadata remain consistent.
+
+4. Verify metadata UX and outputs if you changed form/export behavior:
+  - version guidance and validation still work
+  - grant formatting remains valid (`<funder-code>::<grant-number>`)
+  - `CITATION.cff` and `.zenodo.json` previews still generate
+
+5. Include in your PR description:
+  - what changed
+  - why it changed
+  - how it was tested
+  - screenshots or preview snippets for UI/output changes
+
+6. Confirm governance and policy docs remain consistent with your changes when applicable:
+  - `README.md`
+  - `CODE_OF_CONDUCT.md`
+  - `SECURITY.md`
+
+## Collaborative Distributed Science Practices
+
+OpenCite follows Imageomics collaborative development practices. Contributors are
+expected to:
+
+- Support Imageomics community values of transparency, accountability,
+  collaboration, and safety.
+- Communicate clearly about scope, assumptions, and open questions.
+- Communicate respectfully and align behavior with the Imageomics Code of
+  Conduct.
+- Prefer small, focused pull requests that are easier to review and validate.
+- Give and receive review feedback respectfully and constructively.
+- Give appropriate credit to contributors and prior work.
+- Maintain reproducible and reusable scientific software practices in code,
+  metadata, and documentation.
+
+## Documentation Expectations
+
+If behavior changes, update docs in the same pull request:
+
+- `README.md` for getting started and project overview
+- `CONTRIBUTING.md` for contributor workflow, branching, and pull request expectations
+- `AGENTS.md` for agent workflow or repository guardrails
+
+For detailed repository, GitHub, and GitHub + PyPI + Zenodo operational
+workflows, reference the Imageomics Collaborative Distributed Science guides in
+the References section instead of duplicating those instructions here.
+
+## Release and Metadata Notes
+
+For release-related work, keep release metadata aligned across:
+
+- GitHub release tag and description
+- generated `CITATION.cff`
+- generated `.zenodo.json`
+
+Use semantic versioning and ensure version/date values are consistent.
+
+## References
+
+- Imageomics Repository Guide:
+  https://imageomics.github.io/Collaborative-distributed-science-guide/wiki-guide/GitHub-Repo-Guide/
+- Imageomics GitHub + PyPI + Zenodo Integration:
+  https://imageomics.github.io/Collaborative-distributed-science-guide/wiki-guide/GitHub-PyPI-Zenodo-Integration/
+- Semantic Versioning:
+  https://semver.org/
+- Downstream verification checklist:
+  ./DOWNSTREAM_VERIFICATION_CHECKLIST.md
+
+## CI Expectations
+
+This repository runs a GitHub Actions CI workflow for pull requests and pushes to `main`:
+
+- `.github/workflows/ci.yml`
+
+Your pull request should pass:
+
+- `npm run test`
+- `npm run build`
diff --git a/DOWNSTREAM_VERIFICATION_CHECKLIST.md b/DOWNSTREAM_VERIFICATION_CHECKLIST.md
new file mode 100644
index 0000000..9d46c61
--- /dev/null
+++ b/DOWNSTREAM_VERIFICATION_CHECKLIST.md
@@ -0,0 +1,75 @@
+# Downstream Verification Checklist
+
+Use this checklist to verify generated metadata works in downstream release and citation workflows.
+
+## Prerequisites
+
+- Root metadata files are up to date:
+  - `CITATION.cff`
+  - `.zenodo.json`
+- Local checks pass:
+
+```bash
+npm run test
+npm run build
+npm run validate:metadata
+```
+
+## In-App Export Verification
+
+1. Open the deployed application (recommended for user-facing verification):
+
+  https://imageomics.github.io/OpenCite/
+
+2. If you need local verification during development, start app:
+
+```bash
+npm run dev
+```
+
+3. Fill required fields and generate:
+- `CITATION.cff`
+- `.zenodo.json`
+- ZIP export
+
+4. Confirm ZIP contains:
+- `CITATION.cff`
+- `.zenodo.json`
+- `METADATA_VALIDATION.txt`
+
+5. Confirm `.zenodo.json` filename is preserved exactly (with leading dot).
+
+## GitHub Citation Verification
+
+1. Commit and push `CITATION.cff` to a branch.
+2. Open repository page for that branch.
+3. Verify the "Cite this repository" panel renders expected metadata.
+
+## Zenodo Metadata Verification
+
+1. Open generated `.zenodo.json`.
+2. Confirm key fields:
+- `title`
+- `version`
+- `publication_date`
+- `creators`
+- `grants`
+
+3. If using GitHub-Zenodo integration, perform a test release/deposition flow and verify no ingestion errors.
+
+## Provenance Consistency Check
+
+Confirm release metadata stays consistent across:
+
+- GitHub release tag and notes
+- Generated `CITATION.cff`
+- Generated `.zenodo.json`
+
+## Optional Issue Tracking Prompts
+
+If failures are found, open issues with:
+
+- exact reproduction steps
+- sample generated files (or sanitized excerpts)
+- expected vs observed behavior
+- whether failure occurred in app validation, GitHub rendering, or downstream ingestion
diff --git a/README.md b/README.md
index 1a85647..d908902 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,58 @@
 # OpenCite
 
-Minimal Vite + React single-page app for generating `CITATION.cff` and `.zenodo.json` files from one form.
+OpenCite is a Vite + React single-page app that generates both `CITATION.cff` and `.zenodo.json` from a single metadata form.
+It is browser-first (no Node-only runtime assumptions in app code) and part of
+the Imageomics ecosystem.
+
+Documentation and contributor workflows align with Imageomics principles of
+transparency, accountability, collaboration, and safety.
+
+## Overview
+
+OpenCite helps maintain high-quality, release-ready citation metadata by letting
+you:
+
+- Generate `CITATION.cff` and `.zenodo.json` metadata from one form.
+- Import metadata from GitHub repositories.
+- Validate existing metadata files.
+- Compare repository metadata against citation metadata.
+- Review metadata health checks and recommendations.
+
+Primary user entry point (deployed application):
+https://imageomics.github.io/OpenCite/
+
+The app is built to reduce release-time metadata drift by keeping citation fields consistent across:
+- GitHub release tags and notes
+- `CITATION.cff`
+- `.zenodo.json`
+
+## Supported Metadata Files
+
+OpenCite focuses on:
+
+- `CITATION.cff`
+- `.zenodo.json`
+
+These files should remain consistent with repository information, release
+version, license, authors, grants, and DOI/references when available.
+
+## Using OpenCite
+
+1. Open the deployed application: https://imageomics.github.io/OpenCite/
+2. Enter metadata directly, or import metadata from a GitHub repository.
+3. Review generated `CITATION.cff` and `.zenodo.json` outputs.
+4. Validate metadata before export.
+5. Download generated metadata files (or ZIP export).
+
+Most users should use the deployed application. Local setup is primarily for
+contributors and development/testing workflows.
+
+## Development Information
+
+OpenCite is a React + Vite frontend. It is browser-first for runtime use, with
+Node-based local tooling for development, tests, and metadata checks.
+
+### Development Setup
 
 - [Open OpenCite](https://imageomics.github.io/OpenCite/)
 - [Read the Collaborative Distributed Science Guide](https://imageomics.github.io/Collaborative-distributed-science-guide/)
@@ -12,6 +64,211 @@ npm install
 npm run dev
 ```
 
+Open the local URL shown by Vite and fill in the form. You can then:
+- Generate `CITATION.cff`
+- Generate `.zenodo.json`
+- Download both together as a ZIP
+
+### Running Tests and Build Commands
+
+Run these commands from the repository root:
+
+```bash
+npm run dev      # Start local dev server
+npm run build    # Production build
+npm run test     # Node test runner
+npm run validate:metadata # Validate root CITATION.cff and .zenodo.json
+npm run preview  # Preview production build
+```
+
+`.zenodo.json` validation uses the official Zenodraft CLI via a pinned local
+dependency. The direct equivalent command is:
+
+```bash
+npm exec -- zenodraft metadata validate .zenodo.json
+```
+
+During export, OpenCite validates generated `.zenodo.json` metadata. ZIP exports include `METADATA_VALIDATION.txt` for downstream provenance checks.
+
+## GitHub Import Workflow
+
+1. Paste a GitHub repository URL into the import field.
+2. OpenCite automatically inspects known repository metadata files unless
+   disabled by integration options.
+  - Metadata file import reads from the repository's default branch (typically
+    main).
+  - OpenCite does not currently fetch CITATION.cff from a specific branch,
+    tag, or commit referenced in the GitHub URL.
+3. Supported import sources include:
+   - `CITATION.cff`
+   - `.zenodo.json`
+   - package metadata (for example `package.json`, `pyproject.toml`, `setup.py`,
+     `Cargo.toml`, `pom.xml`)
+   - GitHub repository/release metadata and contributor data
+4. Metadata is merged with precedence rules (release/repository provenance,
+   citation/zenodo/package fields, and contributor enrichment) before loading
+   the editable form.
+5. Imported author lists include contributor-based context and are deduplicated.
+6. Review, adjust, and regenerate metadata files before release.
+
+## Validation Behavior
+
+OpenCite validates metadata at multiple stages:
+
+- Form-level validation before export.
+- `CITATION.cff` and `.zenodo.json` content validation.
+- Comparison checks between repository/GitHub metadata and citation metadata.
+- Health checks that compare imported metadata with available repository/archive
+  signals, including version, repository URL, license, authors, ORCID, DOI,
+  and release information.
+- Missing repository/archive information may produce warnings instead of
+  failures.
+- Author, grant, and reference metadata checks where applicable.
+- Repository-level validation via `npm run validate:metadata` for root
+  `CITATION.cff` and `.zenodo.json`.
+  - `CITATION.cff` uses in-repo citation validation logic.
+  - `.zenodo.json` uses the official Zenodraft validator.
+
+## Metadata Rules
+
+- Version values should match your planned GitHub release tag.
+- Grant IDs must use `<funder-code>::<grant-number>`.
+- Publication date should be a real `YYYY-MM-DD` date.
+- ORCID values are validated when provided.
+- References can be plain lines or structured key/value blocks.
+
+## Semantic Versioning
+
+OpenCite follows [Semantic Versioning](https://semver.org/) (`MAJOR.MINOR.PATCH`).
+
+- `MAJOR`: breaking or incompatible changes
+- `MINOR`: backward-compatible features
+- `PATCH`: backward-compatible bug fixes
+
+Use the exact version/tag string you intend to publish for your GitHub release.
+
+## Release Workflow
+
+When preparing a release:
+
+1. Create the GitHub release and include meaningful release notes.
+2. Ensure the release tag matches the version used in OpenCite.
+3. Update `CITATION.cff` fields as needed:
+	- `version`
+	- `date-released`
+	- release identifiers/URLs
+4. Update `.zenodo.json` metadata when applicable.
+5. Verify release metadata is consistent across GitHub, `CITATION.cff`, and `.zenodo.json`.
+
+OpenCite automatically includes GitHub release and source-tree identifiers in `CITATION.cff` when a version and repository URL are present.
+
+## Grants Autofill
+
+The Grants field includes one-click suggestions for:
+- `021nxhr62::2118240` (Imageomics NSF grant)
+- `021nxhr62::2330423` (ABC NSF grant; NSERC updates may be manual)
+
+Suggestions can be added individually or all at once, and duplicate values are ignored.
+
+## Project Structure
+
+- `src/App.jsx`: main app orchestration and export flow
+- `src/components/MetadataForm.jsx`: form UI and field interactions
+- `src/validation/validation.js`: input validation and normalization
+- `src/metadata/normalizeMetadata.js`: canonical metadata shaping
+- `src/services/citation.js`: `CITATION.cff` serialization
+- `src/services/zenodo.js`: `.zenodo.json` serialization
+- `src/services/githubImporter.js`: GitHub import pipeline
+
+## Repository Readiness Checklist
+
+This checklist is based on the Imageomics Collaborative Distributed Science Guide repository recommendations.
+
+- [x] `README.md` with project overview, usage, release workflow, and citation guidance.
+- [x] `AGENTS.md` with code-agent project context and workflow constraints.
+- [x] `.gitignore` present.
+- [x] machine-readable dependency lockfile (`package-lock.json`) present.
+- [x] `CONTRIBUTING.md` present and linked from README.
+- [x] `LICENSE` file present in repository root.
+- [x] root-level `CITATION.cff` committed for GitHub citation panel.
+- [x] root-level `.zenodo.json` committed for release metadata tracking.
+- [x] `CODE_OF_CONDUCT.md` present.
+- [x] `SECURITY.md` present.
+- [x] CI workflow present for pull requests (`.github/workflows/ci.yml`).
+
+Before initial public release, make sure the unchecked items are completed.
+
+## Contributing
+
+Contributions are welcome for this repository.
+
+See `CONTRIBUTING.md` for project-specific contribution workflow details.
+
+1. Open an issue (or comment on an existing one) describing the change.
+2. Create a branch for your work.
+3. Keep changes focused on the requested feature or bug fix.
+4. Run checks before opening a PR:
+	- `npm run test`
+	- `npm run build`
+5. Open a pull request with:
+	- a clear summary of what changed
+	- why the change is needed
+	- any screenshots or notes for UI changes
+
+### Contribution Scope Guidelines
+
+- Avoid unrelated refactors or broad formatting-only edits.
+- Preserve export behavior for `CITATION.cff` and `.zenodo.json` unless the change explicitly targets that behavior.
+- Keep public service APIs stable, especially under `src/services/`.
+- Prefer updating existing documentation sections instead of creating duplicate docs.
+
+## Learn More
+
+- [Software citation practices (FORCE11 principles)](https://force11.org/info/software-citation-principles/)
+- [GitHub release workflow](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository)
+- [Zenodo GitHub integration guide](https://help.zenodo.org/docs/github/)
+- [Citation File Format schema guide](https://github.com/citation-file-format/citation-file-format/blob/main/schema-guide.md)
+- [Imageomics Repository Guide](https://imageomics.github.io/Collaborative-distributed-science-guide/wiki-guide/GitHub-Repo-Guide/)
+- [Imageomics GitHub + PyPI + Zenodo Integration](https://imageomics.github.io/Collaborative-distributed-science-guide/wiki-guide/GitHub-PyPI-Zenodo-Integration/)
+- [Downstream Verification Checklist](DOWNSTREAM_VERIFICATION_CHECKLIST.md)
+
+## Known Issues
+
+### .zenodo.json download filename issue
+
+- The generated Zenodo metadata file should download with the exact filename:
+  `.zenodo.json`.
+- Some browser/file picker flows may remove the leading period during save.
+- OpenCite uses a direct browser download path for `.zenodo.json` exports to
+  preserve the canonical filename where supported.
+- Verify saved filenames in your browser environment when preparing releases.
+
+### Citation Health limitations
+
+- Health checks were improved to reduce false positives, but some checks remain
+  heuristic because repositories do not always include complete citation
+  metadata.
+- DOI checks depend on available Zenodo/archive signals.
+- Author consistency checks may differ between citation authors and repository
+  contributors because they represent different concepts.
+
+### Metadata provenance limitations
+
+- Health and comparison results are based on merged metadata.
+- Field-level source tracking/provenance is not currently exposed in the UI.
+
+### Citation format limitations
+
+- `CITATION.cff` parsing supports common structures but does not fully model
+  every advanced CFF feature.
+- `preferred-citation` handling remains limited.
+
+## Community and Security
+
+- [Contributing Guide](CONTRIBUTING.md)
+- [Code of Conduct](CODE_OF_CONDUCT.md)
+- [Security Policy](SECURITY.md)
+
 ## Funding and acknowledgements
 
 This work was supported by both the [Imageomics Institute](https://imageomics.org/) and the [AI and Biodiversity Change (ABC) Global Center](http://abcresearchcenter.org/). The Imageomics Institute is funded by the U.S. National Science Foundation's Harnessing the Data Revolution (HDR) program under [Award #2118240](https://www.nsf.gov/awardsearch/showAward?AWD_ID=2118240) (Imageomics: A New Frontier of Biological Information Powered by Knowledge-Guided Machine Learning). The ABC Global Center is funded by the U.S. National Science Foundation under [Award No. 2330423](https://www.nsf.gov/awardsearch/showAward?AWD_ID=2330423&HistoricalAwards=false) and Natural Sciences and Engineering Research Council of Canada under [Award No. 585136](https://www.nserc-crsng.gc.ca/ase-oro/Details-Detailles_eng.asp?id=782440). This work draws on research supported by the Social Sciences and Humanities Research Council. Any opinions, findings and conclusions or recommendations expressed in this material are those of the author(s) and do not necessarily reflect the views of the National Science Foundation, Natural Sciences and Engineering Research Council of Canada, or Social Sciences and Humanities Research Council.
diff --git a/SECURITY.md b/SECURITY.md
new file mode 100644
index 0000000..6b1b4c0
--- /dev/null
+++ b/SECURITY.md
@@ -0,0 +1,24 @@
+# Security Policy
+
+## Supported Versions
+
+OpenCite is currently in active development. Please report security issues for
+the latest version on the default branch.
+
+## Reporting a Vulnerability
+
+Please do not open public GitHub issues for suspected security vulnerabilities.
+
+Instead:
+
+1. Open a private security advisory in this repository (Security tab).
+2. Include details to reproduce the issue and any proof-of-concept material.
+3. Include potential impact and affected components if known.
+
+We will acknowledge receipt as soon as possible and work with you to validate,
+triage, and remediate the issue.
+
+## Disclosure
+
+Please allow time for triage and remediation before public disclosure.
+Coordinated disclosure helps protect users and downstream adopters.
diff --git a/package-lock.json b/package-lock.json
index 6d91beb..afcc5f9 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -8,12 +8,14 @@
       "name": "opencite",
       "version": "0.0.0",
       "dependencies": {
+        "jszip": "^3.10.1",
         "react": "^18.3.1",
         "react-dom": "^18.3.1"
       },
       "devDependencies": {
         "@vitejs/plugin-react": "^4.3.1",
-        "vite": "^5.4.8"
+        "vite": "^5.4.8",
+        "zenodraft": "0.14.1"
       }
     },
     "node_modules/@babel/code-frame": {
@@ -1090,6 +1092,39 @@
         "vite": "^4.2.0 || ^5.0.0 || ^6.0.0 || ^7.0.0"
       }
     },
+    "node_modules/ajv": {
+      "version": "8.20.0",
+      "resolved": "https://registry.npmjs.org/ajv/-/ajv-8.20.0.tgz",
+      "integrity": "sha512-Thbli+OlOj+iMPYFBVBfJ3OmCAnaSyNn4M1vz9T6Gka5Jt9ba/HIR56joy65tY6kx/FCF5VXNB819Y7/GUrBGA==",
+      "dev": true,
+      "dependencies": {
+        "fast-deep-equal": "^3.1.3",
+        "fast-uri": "^3.0.1",
+        "json-schema-traverse": "^1.0.0",
+        "require-from-string": "^2.0.2"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/epoberezkin"
+      }
+    },
+    "node_modules/ajv-formats": {
+      "version": "2.1.1",
+      "resolved": "https://registry.npmjs.org/ajv-formats/-/ajv-formats-2.1.1.tgz",
+      "integrity": "sha512-Wx0Kx52hxE7C18hkMEggYlEifqWZtYaRgouJor+WMdPnQyEK13vgEWyVNup7SoeeoLMsr4kf5h6dOW11I15MUA==",
+      "dev": true,
+      "dependencies": {
+        "ajv": "^8.0.0"
+      },
+      "peerDependencies": {
+        "ajv": "^8.0.0"
+      },
+      "peerDependenciesMeta": {
+        "ajv": {
+          "optional": true
+        }
+      }
+    },
     "node_modules/baseline-browser-mapping": {
       "version": "2.10.32",
       "resolved": "https://registry.npmjs.org/baseline-browser-mapping/-/baseline-browser-mapping-2.10.32.tgz",
@@ -1155,12 +1190,26 @@
         }
       ]
     },
+    "node_modules/commander": {
+      "version": "7.2.0",
+      "resolved": "https://registry.npmjs.org/commander/-/commander-7.2.0.tgz",
+      "integrity": "sha512-QrWXB+ZQSVPmIWIhtEO9H+gwHaMGYiF5ChvoJ+K9ZGHG/sVsa6yiesAD1GC/x46sET00Xlwo1u49RVVVzvcSkw==",
+      "dev": true,
+      "engines": {
+        "node": ">= 10"
+      }
+    },
     "node_modules/convert-source-map": {
       "version": "2.0.0",
       "resolved": "https://registry.npmjs.org/convert-source-map/-/convert-source-map-2.0.0.tgz",
       "integrity": "sha512-Kvp459HrV2FEJ1CAsi1Ku+MY3kasH19TFykTz2xWmMeq6bk2NU3XXvfJ+Q61m0xktWwt+1HSYf3JZsTms3aRJg==",
       "dev": true
     },
+    "node_modules/core-util-is": {
+      "version": "1.0.3",
+      "resolved": "https://registry.npmjs.org/core-util-is/-/core-util-is-1.0.3.tgz",
+      "integrity": "sha512-ZQBvi1DcpJ4GDqanjucZ2Hj3wEO5pZDS89BWbkcrvdxksJorwUDDZamX9ldFkp9aw2lmBDLgkObEA4DWNJ9FYQ=="
+    },
     "node_modules/debug": {
       "version": "4.4.3",
       "resolved": "https://registry.npmjs.org/debug/-/debug-4.4.3.tgz",
@@ -1178,6 +1227,15 @@
         }
       }
     },
+    "node_modules/dotenv": {
+      "version": "10.0.0",
+      "resolved": "https://registry.npmjs.org/dotenv/-/dotenv-10.0.0.tgz",
+      "integrity": "sha512-rlBi9d8jpv9Sf1klPjNfFAuWDjKLwTIJJ/VxtoTwIR6hnZxcEOQCZg2oIL3MWBYw5GpUDKOEnND7LXTbIpQ03Q==",
+      "dev": true,
+      "engines": {
+        "node": ">=10"
+      }
+    },
     "node_modules/electron-to-chromium": {
       "version": "1.5.364",
       "resolved": "https://registry.npmjs.org/electron-to-chromium/-/electron-to-chromium-1.5.364.tgz",
@@ -1231,6 +1289,28 @@
         "node": ">=6"
       }
     },
+    "node_modules/fast-deep-equal": {
+      "version": "3.1.3",
+      "resolved": "https://registry.npmjs.org/fast-deep-equal/-/fast-deep-equal-3.1.3.tgz",
+      "integrity": "sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q==",
+      "dev": true
+    },
+    "node_modules/fast-uri": {
+      "version": "3.1.5",
+      "resolved": "https://registry.npmjs.org/fast-uri/-/fast-uri-3.1.5.tgz",
+      "integrity": "sha512-gHwA1O9LDIcKunMKhObS/HimwtehO1nPUECKAu5TpKgaO19fcWEl4bliWe1jWxVFvIXztJjjQ4L8XQ1EU9f7Jw==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/fastify"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/fastify"
+        }
+      ]
+    },
     "node_modules/fsevents": {
       "version": "2.3.3",
       "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.3.tgz",
@@ -1254,6 +1334,21 @@
         "node": ">=6.9.0"
       }
     },
+    "node_modules/immediate": {
+      "version": "3.0.6",
+      "resolved": "https://registry.npmjs.org/immediate/-/immediate-3.0.6.tgz",
+      "integrity": "sha512-XXOFtyqDjNDAQxVfYxuF7g9Il/IbWmmlQg2MYKOH8ExIT1qg6xc4zyS3HaEEATgs1btfzxq15ciUiY7gjSXRGQ=="
+    },
+    "node_modules/inherits": {
+      "version": "2.0.4",
+      "resolved": "https://registry.npmjs.org/inherits/-/inherits-2.0.4.tgz",
+      "integrity": "sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ=="
+    },
+    "node_modules/isarray": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/isarray/-/isarray-1.0.0.tgz",
+      "integrity": "sha512-VLghIWNM6ELQzo7zwmcg0NmTVyWKYjvIeM83yjp0wRDTmUnrM678fQbcKBo6n2CJEF0szoG//ytg+TKla89ALQ=="
+    },
     "node_modules/js-tokens": {
       "version": "4.0.0",
       "resolved": "https://registry.npmjs.org/js-tokens/-/js-tokens-4.0.0.tgz",
@@ -1271,6 +1366,12 @@
         "node": ">=6"
       }
     },
+    "node_modules/json-schema-traverse": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/json-schema-traverse/-/json-schema-traverse-1.0.0.tgz",
+      "integrity": "sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug==",
+      "dev": true
+    },
     "node_modules/json5": {
       "version": "2.2.3",
       "resolved": "https://registry.npmjs.org/json5/-/json5-2.2.3.tgz",
@@ -1283,6 +1384,25 @@
         "node": ">=6"
       }
     },
+    "node_modules/jszip": {
+      "version": "3.10.1",
+      "resolved": "https://registry.npmjs.org/jszip/-/jszip-3.10.1.tgz",
+      "integrity": "sha512-xXDvecyTpGLrqFrvkrUSoxxfJI5AH7U8zxxtVclpsUtMCq4JQ290LY8AW5c7Ggnr/Y/oK+bQMbqK2qmtk3pN4g==",
+      "dependencies": {
+        "lie": "~3.3.0",
+        "pako": "~1.0.2",
+        "readable-stream": "~2.3.6",
+        "setimmediate": "^1.0.5"
+      }
+    },
+    "node_modules/lie": {
+      "version": "3.3.0",
+      "resolved": "https://registry.npmjs.org/lie/-/lie-3.3.0.tgz",
+      "integrity": "sha512-UaiMJzeWRlEujzAuw5LokY1L5ecNQYZKfmyZ9L7wDHb/p5etKaxXhohBcrw0EYby+G/NA52vRSN4N39dxHAIwQ==",
+      "dependencies": {
+        "immediate": "~3.0.5"
+      }
+    },
     "node_modules/loose-envify": {
       "version": "1.4.0",
       "resolved": "https://registry.npmjs.org/loose-envify/-/loose-envify-1.4.0.tgz",
@@ -1327,6 +1447,26 @@
         "node": "^10 || ^12 || ^13.7 || ^14 || >=15.0.1"
       }
     },
+    "node_modules/node-fetch": {
+      "version": "2.7.0",
+      "resolved": "https://registry.npmjs.org/node-fetch/-/node-fetch-2.7.0.tgz",
+      "integrity": "sha512-c4FRfUm/dbcWZ7U+1Wq0AwCyFL+3nt2bEw05wfxSz+DWpWsitgmSgYmy2dQdWyKC1694ELPqMs/YzUSNozLt8A==",
+      "dev": true,
+      "dependencies": {
+        "whatwg-url": "^5.0.0"
+      },
+      "engines": {
+        "node": "4.x || >=6.0.0"
+      },
+      "peerDependencies": {
+        "encoding": "^0.1.0"
+      },
+      "peerDependenciesMeta": {
+        "encoding": {
+          "optional": true
+        }
+      }
+    },
     "node_modules/node-releases": {
       "version": "2.0.46",
       "resolved": "https://registry.npmjs.org/node-releases/-/node-releases-2.0.46.tgz",
@@ -1336,6 +1476,11 @@
         "node": ">=18"
       }
     },
+    "node_modules/pako": {
+      "version": "1.0.11",
+      "resolved": "https://registry.npmjs.org/pako/-/pako-1.0.11.tgz",
+      "integrity": "sha512-4hLB8Py4zZce5s4yd9XzopqwVv/yGNhV1Bl8NTmCq1763HeK2+EwVTv+leGeL13Dnh2wfbqowVPXCIO0z4taYw=="
+    },
     "node_modules/picocolors": {
       "version": "1.1.1",
       "resolved": "https://registry.npmjs.org/picocolors/-/picocolors-1.1.1.tgz",
@@ -1370,6 +1515,11 @@
         "node": "^10 || ^12 || >=14"
       }
     },
+    "node_modules/process-nextick-args": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/process-nextick-args/-/process-nextick-args-2.0.1.tgz",
+      "integrity": "sha512-3ouUOpQhtgrbOa17J7+uxOTpITYWaGP7/AhoR3+A+/1e9skrzelGi/dXzEYyvbxubEF6Wn2ypscTKiKJFFn1ag=="
+    },
     "node_modules/react": {
       "version": "18.3.1",
       "resolved": "https://registry.npmjs.org/react/-/react-18.3.1.tgz",
@@ -1402,6 +1552,29 @@
         "node": ">=0.10.0"
       }
     },
+    "node_modules/readable-stream": {
+      "version": "2.3.8",
+      "resolved": "https://registry.npmjs.org/readable-stream/-/readable-stream-2.3.8.tgz",
+      "integrity": "sha512-8p0AUk4XODgIewSi0l8Epjs+EVnWiK7NoDIEGU0HhE7+ZyY8D1IMY7odu5lRrFXGg71L15KG8QrPmum45RTtdA==",
+      "dependencies": {
+        "core-util-is": "~1.0.0",
+        "inherits": "~2.0.3",
+        "isarray": "~1.0.0",
+        "process-nextick-args": "~2.0.0",
+        "safe-buffer": "~5.1.1",
+        "string_decoder": "~1.1.1",
+        "util-deprecate": "~1.0.1"
+      }
+    },
+    "node_modules/require-from-string": {
+      "version": "2.0.2",
+      "resolved": "https://registry.npmjs.org/require-from-string/-/require-from-string-2.0.2.tgz",
+      "integrity": "sha512-Xf0nWe6RseziFMu+Ap9biiUbmplq6S9/p+7w7YXP/JBHhrUDDUhwa+vANyubuqfZWTveU//DYVGsDG7RKL/vEw==",
+      "dev": true,
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
     "node_modules/rollup": {
       "version": "4.60.4",
       "resolved": "https://registry.npmjs.org/rollup/-/rollup-4.60.4.tgz",
@@ -1446,6 +1619,11 @@
         "fsevents": "~2.3.2"
       }
     },
+    "node_modules/safe-buffer": {
+      "version": "5.1.2",
+      "resolved": "https://registry.npmjs.org/safe-buffer/-/safe-buffer-5.1.2.tgz",
+      "integrity": "sha512-Gd2UZBJDkXlY7GbJxfsE8/nvKkUEU1G38c1siN6QP6a9PT9MmHB8GnpscSmMJSoF8LOIrt8ud/wPtojys4G6+g=="
+    },
     "node_modules/scheduler": {
       "version": "0.23.2",
       "resolved": "https://registry.npmjs.org/scheduler/-/scheduler-0.23.2.tgz",
@@ -1463,6 +1641,11 @@
         "semver": "bin/semver.js"
       }
     },
+    "node_modules/setimmediate": {
+      "version": "1.0.5",
+      "resolved": "https://registry.npmjs.org/setimmediate/-/setimmediate-1.0.5.tgz",
+      "integrity": "sha512-MATJdZp8sLqDl/68LfQmbP8zKPLQNV6BIZoIgrscFDQ+RsvK/BxeDQOgyxKKoh0y/8h3BqVFnCqQ/gd+reiIXA=="
+    },
     "node_modules/source-map-js": {
       "version": "1.2.1",
       "resolved": "https://registry.npmjs.org/source-map-js/-/source-map-js-1.2.1.tgz",
@@ -1472,6 +1655,20 @@
         "node": ">=0.10.0"
       }
     },
+    "node_modules/string_decoder": {
+      "version": "1.1.1",
+      "resolved": "https://registry.npmjs.org/string_decoder/-/string_decoder-1.1.1.tgz",
+      "integrity": "sha512-n/ShnvDi6FHbbVfviro+WojiFzv+s8MPMHBczVePfUpDJLwoLT0ht1l4YwBCbi8pJAveEEdnkHyPyTP/mzRfwg==",
+      "dependencies": {
+        "safe-buffer": "~5.1.0"
+      }
+    },
+    "node_modules/tr46": {
+      "version": "0.0.3",
+      "resolved": "https://registry.npmjs.org/tr46/-/tr46-0.0.3.tgz",
+      "integrity": "sha512-N3WMsuqV66lT30CrXNbEjx4GEwlow3v6rr4mCcv6prnfwhS01rkgyFdjPNBYd9br7LpXV1+Emh01fHnq2Gdgrw==",
+      "dev": true
+    },
     "node_modules/update-browserslist-db": {
       "version": "1.2.3",
       "resolved": "https://registry.npmjs.org/update-browserslist-db/-/update-browserslist-db-1.2.3.tgz",
@@ -1502,6 +1699,11 @@
         "browserslist": ">= 4.21.0"
       }
     },
+    "node_modules/util-deprecate": {
+      "version": "1.0.2",
+      "resolved": "https://registry.npmjs.org/util-deprecate/-/util-deprecate-1.0.2.tgz",
+      "integrity": "sha512-EPD5q1uXyFxJpCrLnCc1nHnq3gOa6DZBocAIiI2TaSCA7VCJ1UJDMagCzIkXNsUYfD1daK//LTEQ8xiIbrHtcw=="
+    },
     "node_modules/vite": {
       "version": "5.4.21",
       "resolved": "https://registry.npmjs.org/vite/-/vite-5.4.21.tgz",
@@ -1561,11 +1763,48 @@
         }
       }
     },
+    "node_modules/webidl-conversions": {
+      "version": "3.0.1",
+      "resolved": "https://registry.npmjs.org/webidl-conversions/-/webidl-conversions-3.0.1.tgz",
+      "integrity": "sha512-2JAn3z8AR6rjK8Sm8orRC0h/bcl/DqL7tRPdGZ4I1CjdF+EaMLmYxBHyXuKL849eucPFhvBoxMsflfOb8kxaeQ==",
+      "dev": true
+    },
+    "node_modules/whatwg-url": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/whatwg-url/-/whatwg-url-5.0.0.tgz",
+      "integrity": "sha512-saE57nupxk6v3HY35+jzBwYa0rKSy0XR8JSxZPwgLr7ys0IBzhGviA1/TUGJLmSVqs8pb9AnvICXEuOHLprYTw==",
+      "dev": true,
+      "dependencies": {
+        "tr46": "~0.0.3",
+        "webidl-conversions": "^3.0.0"
+      }
+    },
     "node_modules/yallist": {
       "version": "3.1.1",
       "resolved": "https://registry.npmjs.org/yallist/-/yallist-3.1.1.tgz",
       "integrity": "sha512-a4UGQaWPH59mOXUYnAG2ewncQS4i4F43Tv3JoAM+s2VDAmS9NsK8GpDMLrCHPksFT7h3K6TOoUNn2pb7RoXx4g==",
       "dev": true
+    },
+    "node_modules/zenodraft": {
+      "version": "0.14.1",
+      "resolved": "https://registry.npmjs.org/zenodraft/-/zenodraft-0.14.1.tgz",
+      "integrity": "sha512-1jOz5m8rgvnGWvBkxnmZCXbmSj3VB+pO+eNXMJkkrJEjW6+FRmVTUKeOUaFpVOjWRmGIyY8c5BRU8CYwiqHhHA==",
+      "dev": true,
+      "dependencies": {
+        "ajv": "^8.12.0",
+        "ajv-formats": "^2.1.1",
+        "commander": "^7.2.0",
+        "dotenv": "^10.0.0",
+        "node-fetch": "^2.6.7"
+      },
+      "bin": {
+        "zenodraft": "bin/index.js",
+        "zenodraft-autocomplete": "bin/autocomplete.js"
+      },
+      "engines": {
+        "node": ">=20.0.0",
+        "npm": ">=10.0.0"
+      }
     }
   }
 }
diff --git a/package.json b/package.json
index 63c1d16..eba60ea 100644
--- a/package.json
+++ b/package.json
@@ -6,14 +6,18 @@
   "scripts": {
     "dev": "vite",
     "build": "vite build",
+    "test": "node --test",
+    "validate:metadata": "node ./scripts/validate-metadata.mjs",
     "preview": "vite preview"
   },
   "dependencies": {
+    "jszip": "^3.10.1",
     "react": "^18.3.1",
     "react-dom": "^18.3.1"
   },
   "devDependencies": {
     "@vitejs/plugin-react": "^4.3.1",
-    "vite": "^5.4.8"
+    "vite": "^5.4.8",
+    "zenodraft": "0.14.1"
   }
-}
\ No newline at end of file
+}
diff --git a/scripts/validate-metadata.mjs b/scripts/validate-metadata.mjs
new file mode 100644
index 0000000..68b99fb
--- /dev/null
+++ b/scripts/validate-metadata.mjs
@@ -0,0 +1,81 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import process from 'node:process';
+import { exec } from 'node:child_process';
+import { promisify } from 'node:util';
+
+import { validateCitationCffText } from '../src/services/citationValidation.js';
+
+const execAsync = promisify(exec);
+
+async function readText(relativePath) {
+  const filePath = path.resolve(process.cwd(), relativePath);
+  return readFile(filePath, 'utf8');
+}
+
+function printResult(title, result) {
+  console.log(`\n${title}`);
+  console.log('-'.repeat(title.length));
+  console.log(`Status: ${result.isValid ? 'PASS' : 'FAIL'}`);
+
+  if (result.errors.length > 0) {
+    console.log('Errors:');
+    for (const error of result.errors) {
+      console.log(`- ${error}`);
+    }
+  }
+
+  if (result.warnings.length > 0) {
+    console.log('Warnings:');
+    for (const warning of result.warnings) {
+      console.log(`- ${warning}`);
+    }
+  }
+}
+
+async function runZenodraftValidation() {
+  const command = 'npm exec -- zenodraft metadata validate .zenodo.json';
+
+  console.log('\n.zenodo.json validation (zenodraft)');
+  console.log('---------------------------------');
+
+  try {
+    const { stdout, stderr } = await execAsync(command, { cwd: process.cwd() });
+    if (stdout) {
+      process.stdout.write(stdout);
+    }
+    if (stderr) {
+      process.stderr.write(stderr);
+    }
+    return true;
+  } catch (error) {
+    if (error && typeof error === 'object') {
+      if ('stdout' in error && error.stdout) {
+        process.stdout.write(String(error.stdout));
+      }
+      if ('stderr' in error && error.stderr) {
+        process.stderr.write(String(error.stderr));
+      }
+    }
+    return false;
+  }
+}
+
+async function main() {
+  const citationText = await readText('CITATION.cff');
+
+  const citationResult = validateCitationCffText(citationText);
+
+  printResult('CITATION.cff validation', citationResult);
+  const zenodoIsValid = await runZenodraftValidation();
+
+  const hasErrors = !citationResult.isValid || !zenodoIsValid;
+  if (hasErrors) {
+    process.exitCode = 1;
+  }
+}
+
+main().catch((error) => {
+  console.error('Failed to validate metadata files:', error);
+  process.exitCode = 1;
+});
diff --git a/src/App.jsx b/src/App.jsx
index 5daa68b..01ce35e 100644
--- a/src/App.jsx
+++ b/src/App.jsx
@@ -1,17 +1,17 @@
-import { useEffect, useMemo, useState } from 'react';
+import { useMemo, useRef, useState } from 'react';
+import JSZip from 'jszip';
 import { MetadataForm } from './components/MetadataForm.jsx';
 import { normalizeMetadata } from './metadata/normalizeMetadata.js';
+import { importGithubMetadata } from './services/githubImporter.js';
+import { pickPreferredOrcidCandidate, searchOrcidCandidates } from './services/orcidSearch.js';
 import { toCitationCff } from './services/citation.js';
+import { validateCitationCffText } from './services/citationValidation.js';
 import { toZenodoJson } from './services/zenodo.js';
+import { validateZenodoJsonText } from './services/zenodoValidation.js';
 import { normalizeFormInput, validateMetadata } from './validation/validation.js';
 
-const PIPELINE_STEPS = [
-  'Import',
-  'Review Metadata',
-  'Validate',
-  'Export Citation Files',
-];
-
+const CITATION_FILENAME = 'CITATION.cff';
+const ZENODO_FILENAME = '.zenodo.json';
 function createAuthorId() {
   if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
     return crypto.randomUUID();
@@ -31,7 +31,7 @@ const initialForm = {
   keywords: '',
   typeOfWork: 'software',
   customTypeOfWork: '',
-  version: '',
+  version: '0.1.0',
   publicationDate: '',
   repositoryCode: '',
   doi: '',
@@ -56,110 +56,492 @@ const licenseOptions = [
   'GPL-3.0-only',
 ];
 
+const grantSuggestions = [
+  {
+    id: '021nxhr62::2118240',
+    label: 'Imageomics NSF grant',
+    note: 'Imageomics program grant (NSF funder code 021nxhr62).',
+  },
+  {
+    id: '021nxhr62::2330423',
+    label: 'ABC NSF grant',
+    note: 'ABC NSF grant; NSERC portion requires manual update when applicable.',
+  },
+];
+
+const REQUIRED_FIELD_LABELS = {
+  title: 'Title',
+  authors: 'Authors',
+  license: 'License',
+  typeOfWork: 'Type',
+  version: 'Version',
+  publicationDate: 'Publication date',
+  grants: 'Grants',
+};
+
+const WARNING_MESSAGE_MAX_LENGTH = 180;
+
+function truncateMessage(message, maxLength = WARNING_MESSAGE_MAX_LENGTH) {
+  const normalized = String(message ?? '').replace(/\s+/g, ' ').trim();
+
+  if (normalized.length <= maxLength) {
+    return normalized;
+  }
+
+  return `${normalized.slice(0, Math.max(0, maxLength - 1)).trimEnd()}…`;
+}
+
+function formatWarningCode(code) {
+  const value = String(code ?? '').trim();
+  if (!value) {
+    return 'Warning';
+  }
+
+  return value
+    .split(/[-_\s]+/)
+    .filter(Boolean)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join(' ');
+}
+
+function formatWarningList(warnings) {
+  const groups = new Map();
+
+  for (const warning of warnings) {
+    const code = String(warning?.code ?? 'warning');
+    const shortMessage = truncateMessage(warning?.message ?? 'Warning');
+    const group = groups.get(code) ?? {
+      code,
+      total: 0,
+      messages: new Map(),
+    };
+
+    group.total += 1;
+    group.messages.set(shortMessage, (group.messages.get(shortMessage) ?? 0) + 1);
+    groups.set(code, group);
+  }
+
+  return [...groups.values()].map((group) => {
+    const messageParts = [...group.messages.entries()].map(([message, count]) =>
+      count > 1 ? `${message} (${count}x)` : message,
+    );
+
+    if (group.total === 1 && messageParts.length === 1) {
+      return messageParts[0];
+    }
+
+    return `${formatWarningCode(group.code)} (${group.total}): ${messageParts.join(' | ')}`;
+  });
+}
+
+function formatReviewStatus(value) {
+  const status = String(value ?? '').toLowerCase();
+
+  if (status === 'correct') return 'Correct';
+  if (status === 'missing') return 'Missing';
+  if (status === 'outdated') return 'Outdated';
+  if (status === 'invalid') return 'Invalid';
+  return 'Review';
+}
+
+function formatReviewAction(value) {
+  const action = String(value ?? '').trim();
+
+  if (action === 'keep-file') return 'Keep file';
+  if (action === 'update-field') return 'Update field';
+  if (action === 'generate-file') return 'Generate file';
+  if (action === 'regenerate-file') return 'Regenerate file';
+  return 'Review';
+}
+
+function formatHealthStatus(value) {
+  const status = String(value ?? '').toLowerCase();
+  if (status === 'pass') return 'PASS';
+  if (status === 'warning') return 'WARNING';
+  if (status === 'error') return 'ERROR';
+  return 'CHECK';
+}
+
+function healthBadgeClass(value) {
+  const status = String(value ?? '').toLowerCase();
+  if (status === 'pass') return 'health-badge health-badge-pass';
+  if (status === 'warning') return 'health-badge health-badge-warning';
+  if (status === 'error') return 'health-badge health-badge-error';
+  return 'health-badge';
+}
+
+function formatComparisonStatus(value) {
+  const status = String(value ?? '').toLowerCase();
+  if (status === 'identical') return 'IDENTICAL';
+  if (status === 'different') return 'DIFFERENT';
+  if (status === 'missing') return 'MISSING';
+  if (status === 'cannot determine') return 'CANNOT DETERMINE';
+  return 'UNKNOWN';
+}
+
+function summarizeComparisonIssue(item) {
+  if (!item) {
+    return '';
+  }
+
+  const fieldLabel = String(item.field ?? '').replace(/_/g, ' ');
+  if (item.status === 'different') {
+    return `${fieldLabel} is outdated`;
+  }
+
+  if (item.status === 'missing') {
+    return `${fieldLabel} is missing`;
+  }
+
+  if (item.status === 'cannot determine') {
+    return `${fieldLabel} cannot be determined from GitHub metadata`;
+  }
+
+  return '';
+}
+
+function buildImportReviewSummary(importStatus) {
+  const warnings = [];
+  const recommendations = [];
+
+  const healthIssues = (importStatus.healthScan || []).filter((check) => check.status === 'warning' || check.status === 'error');
+  for (const issue of healthIssues) {
+    const text = String(issue.description || '').trim();
+    if (text) {
+      warnings.push(text);
+    }
+
+    const recommendation = String(issue.recommendation || '').trim();
+    if (recommendation) {
+      recommendations.push(recommendation);
+    }
+  }
+
+  const comparisonIssues = (importStatus.comparisons || []).filter((item) => item.status !== 'identical');
+  for (const issue of comparisonIssues) {
+    const text = summarizeComparisonIssue(issue);
+    if (text) {
+      warnings.push(text);
+    }
+
+    const recommendation = String(issue.recommendation || '').trim();
+    if (recommendation) {
+      recommendations.push(recommendation);
+    }
+  }
+
+  const uniqueWarnings = [...new Set(warnings)].filter(Boolean);
+  const uniqueRecommendations = [...new Set(recommendations)].filter(Boolean);
+  const healthy = uniqueWarnings.length === 0 && (importStatus.errors || []).length === 0;
+
+  return {
+    healthy,
+    warningCount: uniqueWarnings.length,
+    warnings: uniqueWarnings,
+    recommendations: uniqueRecommendations,
+  };
+}
+
+function formatValidationSummary(errors) {
+  return Object.entries(errors)
+    .map(([key, value]) => {
+      if (key === 'authorOrcid' && value && typeof value === 'object') {
+        const firstEntry = Object.values(value)[0];
+        return firstEntry ? `Author ORCID: ${firstEntry}` : 'Author ORCID: fix the highlighted ORCID fields.';
+      }
+
+      if (key === 'authors') {
+        return value;
+      }
+
+      if (REQUIRED_FIELD_LABELS[key]) {
+        return `${REQUIRED_FIELD_LABELS[key]}: ${value}`;
+      }
+
+      return value;
+    })
+    .filter(Boolean);
+}
+
+function getValidationMissingFields(errors) {
+  const fields = [];
+
+  if (errors.title) fields.push('Title');
+  if (errors.authors) fields.push('Authors');
+  if (errors.license) fields.push('License');
+  if (errors.typeOfWork) fields.push('Type');
+  if (errors.version) fields.push('Version');
+  if (errors.publicationDate) fields.push('Publication date');
+  if (errors.grants) fields.push('Grants');
+
+  if (errors.authorOrcid && typeof errors.authorOrcid === 'object') {
+    fields.push('Author ORCID');
+  }
+
+  return fields;
+}
+
+function createBlankAuthor() {
+  return { givenNames: '', familyNames: '', orcid: '', affiliation: '' };
+}
+
+function metadataToForm(metadata) {
+  return {
+    title: String(metadata.title ?? ''),
+    authors:
+      Array.isArray(metadata.authors) && metadata.authors.length > 0
+        ? metadata.authors.map((author) => ({
+            givenNames: String(author.givenNames ?? ''),
+            familyNames: String(author.familyNames ?? ''),
+            orcid: String(author.orcid ?? ''),
+            affiliation: String(author.affiliation ?? ''),
+          }))
+        : [createBlankAuthor()],
+    license: String(metadata.license ?? ''),
+    keywords: Array.isArray(metadata.keywords) ? metadata.keywords.join(', ') : '',
+    typeOfWork: String(metadata.typeOfWork ?? 'software'),
+    customTypeOfWork: String(metadata.customTypeOfWork ?? ''),
+    version: String(metadata.version ?? ''),
+    publicationDate: String(metadata.publicationDate ?? ''),
+    repositoryCode: String(metadata.repositoryCode ?? ''),
+    doi: String(metadata.doi ?? ''),
+    abstract: String(metadata.abstract ?? ''),
+    references: Array.isArray(metadata.references) ? metadata.references.join('\n') : '',
+    grants: Array.isArray(metadata.grants) ? metadata.grants.join('\n') : '',
+  };
+}
+
 function downloadFile(filename, content, mimeType) {
   const blob = new Blob([content], { type: mimeType });
   const url = URL.createObjectURL(blob);
   const anchor = document.createElement('a');
   anchor.href = url;
   anchor.download = filename;
+  anchor.style.display = 'none';
+  document.body.appendChild(anchor);
   anchor.click();
-  setTimeout(() => URL.revokeObjectURL(url), 0);
+  setTimeout(() => {
+    anchor.remove();
+    URL.revokeObjectURL(url);
+  }, 1500);
 }
 
-function wait(milliseconds) {
-  return new Promise((resolve) => {
-    setTimeout(resolve, milliseconds);
-  });
-}
+function confirmMissingCitationReferences(citationText) {
+  const hasReferencesSection = /^references:\s*$/m.test(String(citationText ?? ''));
+  if (hasReferencesSection) {
+    return true;
+  }
 
-function parseRepositoryLabel(url) {
-  try {
-    const parsed = new URL(url);
-    const [owner, repo] = parsed.pathname.split('/').filter(Boolean);
-    if (owner && repo) {
-      return `${owner}/${repo.replace(/\.git$/i, '')}`;
-    }
-  } catch {
-    return '';
+  const message = 'CITATION.cff currently has no references section. Continue export anyway?';
+
+  if (typeof window !== 'undefined' && typeof window.confirm === 'function') {
+    return window.confirm(message);
   }
 
-  return '';
+  return true;
+}
+
+function canUseNativeFilePicker() {
+  return typeof window !== 'undefined' && typeof window.showSaveFilePicker === 'function';
+}
+
+async function createMetadataZipBlob(citationPreview, zenodoPreview, validationReport) {
+  const zip = new JSZip();
+  zip.file(CITATION_FILENAME, citationPreview);
+  zip.file(ZENODO_FILENAME, zenodoPreview);
+  zip.file('METADATA_VALIDATION.txt', validationReport);
+
+  return zip.generateAsync({ type: 'blob' });
 }
 
-function isGithubRepositoryUrl(url) {
-  try {
-    const parsed = new URL(url);
-    const [owner, repo] = parsed.pathname.split('/').filter(Boolean);
-    return parsed.hostname.toLowerCase() === 'github.com' && Boolean(owner && repo);
-  } catch {
-    return false;
+async function saveFileWithPicker(filename, content, mimeType, pickerTypes = []) {
+  if (canUseNativeFilePicker()) {
+    try {
+      const fileHandle = await window.showSaveFilePicker({
+        suggestedName: filename,
+        types: pickerTypes,
+      });
+      const writable = await fileHandle.createWritable();
+      const data = content instanceof Blob ? content : new Blob([content], { type: mimeType });
+      await writable.write(data);
+      await writable.close();
+      return true;
+    } catch (error) {
+      if (error instanceof Error && error.name === 'AbortError') {
+        return false;
+      }
+    }
   }
+
+  downloadFile(filename, content, mimeType);
+  return true;
 }
 
 export default function App() {
+  const [activePage, setActivePage] = useState('generator');
   const [form, setForm] = useState(initialForm);
+  const [githubUrl, setGithubUrl] = useState('');
+  const [importStatus, setImportStatus] = useState({ loading: false, warnings: [], errors: [], review: null, healthScan: [], comparisons: [] });
+  const [isZipping, setIsZipping] = useState(false);
+  const [isDownloadingCitation, setIsDownloadingCitation] = useState(false);
+  const [isDownloadingZenodo, setIsDownloadingZenodo] = useState(false);
   const [previewType, setPreviewType] = useState('citation');
-  const [githubImportUrl, setGithubImportUrl] = useState('');
-  const [importStatus, setImportStatus] = useState({
-    state: 'idle',
-    message: 'Paste a GitHub repository URL to begin.',
-    step: 0,
-  });
-  const [downloadNotice, setDownloadNotice] = useState({ kind: '', message: '' });
-  const [theme, setTheme] = useState(() => {
-    if (typeof window === 'undefined') {
-      return 'light';
-    }
-
-    const savedTheme = window.localStorage.getItem('opencite-theme');
-    if (savedTheme === 'light' || savedTheme === 'dark') {
-      return savedTheme;
-    }
-
-    return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
-  });
+  const [copyState, setCopyState] = useState('idle');
+  const [orcidSuggestions, setOrcidSuggestions] = useState({});
+  const [exportNotice, setExportNotice] = useState({ kind: '', message: '', details: [] });
+  const importRequestIdRef = useRef(0);
   const normalizedForm = useMemo(() => normalizeFormInput(form), [form]);
   const normalizedMetadata = useMemo(() => normalizeMetadata(normalizedForm), [normalizedForm]);
   const validationErrors = useMemo(() => validateMetadata(normalizedForm, typeOptions), [normalizedForm]);
-  const hasValidationErrors = Object.keys(validationErrors).length > 0;
-  const hasMetadataCore = Boolean(
-    normalizedForm.title.trim()
-    || normalizedForm.authors.some((author) => author.givenNames || author.familyNames),
+  const warningDisplayList = useMemo(
+    () => formatWarningList(importStatus.warnings),
+    [importStatus.warnings],
   );
-  const currentPipelineStep = useMemo(() => {
-    if (!normalizedForm.repositoryCode.trim()) {
-      return 1;
+  const healthScanSummary = useMemo(() => {
+    const counts = { pass: 0, warning: 0, error: 0 };
+    for (const check of importStatus.healthScan) {
+      const status = String(check?.status ?? '').toLowerCase();
+      if (status === 'pass' || status === 'warning' || status === 'error') {
+        counts[status] += 1;
+      }
     }
+    return counts;
+  }, [importStatus.healthScan]);
+  const healthPassChecks = useMemo(
+    () => importStatus.healthScan.filter((check) => String(check?.status ?? '').toLowerCase() === 'pass'),
+    [importStatus.healthScan],
+  );
+  const healthWarningChecks = useMemo(
+    () => importStatus.healthScan.filter((check) => String(check?.status ?? '').toLowerCase() === 'warning'),
+    [importStatus.healthScan],
+  );
+  const healthErrorChecks = useMemo(
+    () => importStatus.healthScan.filter((check) => String(check?.status ?? '').toLowerCase() === 'error'),
+    [importStatus.healthScan],
+  );
+  const importReviewSummary = useMemo(
+    () => buildImportReviewSummary(importStatus),
+    [importStatus],
+  );
 
-    if (!hasMetadataCore) {
-      return 2;
+  const citationPreview = useMemo(() => toCitationCff(normalizedMetadata), [normalizedMetadata]);
+  const zenodoPreview = useMemo(() => toZenodoJson(normalizedMetadata), [normalizedMetadata]);
+  const citationValidation = useMemo(
+    () => validateCitationCffText(citationPreview),
+    [citationPreview],
+  );
+  const zenodoValidation = useMemo(
+    () => validateZenodoJsonText(zenodoPreview),
+    [zenodoPreview],
+  );
+
+  const metadataValidationReport = useMemo(
+    () => [citationValidation.report, '', zenodoValidation.report].join('\n'),
+    [citationValidation.report, zenodoValidation.report],
+  );
+
+  function showValidationNotice(errors) {
+    const details = formatValidationSummary(errors);
+    const missingFields = getValidationMissingFields(errors);
+    setExportNotice({
+      kind: 'validation',
+      message: missingFields.length > 0
+        ? `Missing or invalid fields: ${missingFields.join(', ')}.`
+        : 'Some required values are missing or invalid. Review the highlighted fields below.',
+      details: details.length > 0 ? details : ['Review the highlighted fields below.'],
+    });
+
+    if (typeof window !== 'undefined' && typeof window.scrollTo === 'function') {
+      window.scrollTo({ top: 0, behavior: 'smooth' });
     }
+  }
+
+  function clearExportNotice() {
+    setExportNotice({ kind: '', message: '', details: [] });
+  }
+
+  function openReviewedMetadataInGenerator() {
+    setActivePage('generator');
 
-    if (hasValidationErrors) {
-      return 3;
+    if (typeof window !== 'undefined' && typeof window.scrollTo === 'function') {
+      window.scrollTo({ top: 0, behavior: 'smooth' });
     }
+  }
 
-    return 4;
-  }, [normalizedForm.repositoryCode, hasMetadataCore, hasValidationErrors]);
-  const authorSummary = useMemo(() => {
-    return normalizedMetadata.authors
-      .map((author) => author.zenodoName || `${author.citationAuthor?.['family-names'] || ''}, ${author.citationAuthor?.['given-names'] || ''}`.trim())
-      .filter(Boolean);
-  }, [normalizedMetadata.authors]);
+  function renderHealthCheckCard(check, key) {
+    return (
+      <li key={key} className="health-item">
+        <div className="health-item-header">
+          <span className={healthBadgeClass(check.status)}>{formatHealthStatus(check.status)}</span>
+          <strong>{check.title}</strong>
+        </div>
+        <p className="health-item-description">{check.description}</p>
+        {check.recommendation ? (
+          <p className="health-item-recommendation">
+            <span>Recommendation:</span> {check.recommendation}
+          </p>
+        ) : null}
+      </li>
+    );
+  }
 
-  const citationPreview = useMemo(() => toCitationCff(normalizedMetadata), [normalizedMetadata]);
-  const zenodoPreview = useMemo(() => toZenodoJson(normalizedMetadata), [normalizedMetadata]);
+  async function downloadCitationFile() {
+    downloadFile(CITATION_FILENAME, citationPreview, 'text/yaml;charset=utf-8');
+  }
 
-  useEffect(() => {
-    document.documentElement.setAttribute('data-theme', theme);
-    window.localStorage.setItem('opencite-theme', theme);
-  }, [theme]);
+  async function downloadZenodoFile() {
+    // Use direct download to preserve the exact leading-dot filename `.zenodo.json`.
+    downloadFile(ZENODO_FILENAME, zenodoPreview, 'application/json;charset=utf-8');
+  }
 
   function updateField(event) {
     const { name, value } = event.target;
     setForm((current) => ({ ...current, [name]: value }));
   }
 
+  function appendGrantSuggestion(grantId) {
+    const normalizedGrantId = String(grantId ?? '').trim();
+    if (!normalizedGrantId) {
+      return;
+    }
+
+    setForm((current) => {
+      const existing = String(current.grants ?? '')
+        .split('\n')
+        .map((line) => line.trim())
+        .filter(Boolean);
+
+      if (existing.includes(normalizedGrantId)) {
+        return current;
+      }
+
+      return {
+        ...current,
+        grants: [...existing, normalizedGrantId].join('\n'),
+      };
+    });
+  }
+
+  function appendAllGrantSuggestions() {
+    setForm((current) => {
+      const existing = new Set(
+        String(current.grants ?? '')
+          .split('\n')
+          .map((line) => line.trim())
+          .filter(Boolean),
+      );
+
+      for (const suggestion of grantSuggestions) {
+        existing.add(suggestion.id);
+      }
+
+      return {
+        ...current,
+        grants: [...existing].join('\n'),
+      };
+    });
+  }
+
   function updateAuthorField(index, field, value) {
     setForm((current) => ({
       ...current,
@@ -182,279 +564,771 @@ export default function App() {
           ? current.authors.filter((_, i) => i !== index)
           : [createAuthor()],
     }));
+    setOrcidSuggestions((current) => {
+      const next = {};
+      for (const [key, value] of Object.entries(current)) {
+        const suggestionIndex = Number(key);
+        if (!Number.isInteger(suggestionIndex) || suggestionIndex === index) {
+          continue;
+        }
+
+        next[suggestionIndex > index ? suggestionIndex - 1 : suggestionIndex] = value;
+      }
+      return next;
+    });
   }
 
-  function handleDownloadCitation() {
-    if (hasValidationErrors) {
-      alert(Object.values(validationErrors).join('\n'));
-      setDownloadNotice({ kind: 'error', message: 'Fix validation issues before generating citation files.' });
+  function reorderAuthor(index, direction) {
+    const nextIndex = index + direction;
+    if (nextIndex < 0 || nextIndex >= form.authors.length) {
       return;
     }
 
-    downloadFile('CITATION.cff', citationPreview, 'text/yaml;charset=utf-8');
-    setDownloadNotice({
-      kind: 'success',
-      message: 'Citation metadata generated. CITATION.cff is ready and your export pipeline is active.',
+    setForm((current) => {
+      if (nextIndex < 0 || nextIndex >= current.authors.length) {
+        return current;
+      }
+
+      const authors = [...current.authors];
+      [authors[index], authors[nextIndex]] = [authors[nextIndex], authors[index]];
+
+      return {
+        ...current,
+        authors,
+      };
+    });
+
+    setOrcidSuggestions((current) => {
+      const next = { ...current };
+      const currentIndexValue = next[index];
+      next[index] = next[nextIndex];
+      next[nextIndex] = currentIndexValue;
+
+      return next;
     });
   }
 
-  function handleDownloadZenodo() {
-    if (hasValidationErrors) {
-      alert(Object.values(validationErrors).join('\n'));
-      setDownloadNotice({ kind: 'error', message: 'Fix validation issues before generating citation files.' });
-      return;
+  async function resolveOrcidSuggestionsForAuthors(nextForm) {
+    const authors = Array.isArray(nextForm.authors) ? nextForm.authors : [];
+    const nextAuthors = [...authors];
+    const nextSuggestions = {};
+
+    for (let index = 0; index < authors.length; index += 1) {
+      const author = authors[index];
+      if (String(author?.orcid ?? '').trim()) {
+        continue;
+      }
+
+      if (!String(author?.givenNames ?? '').trim() || !String(author?.familyNames ?? '').trim()) {
+        continue;
+      }
+
+      try {
+        const suggestions = await searchOrcidCandidates(author);
+        const preferred = pickPreferredOrcidCandidate(author, suggestions);
+
+        if (preferred) {
+          nextAuthors[index] = {
+            ...nextAuthors[index],
+            orcid: preferred.orcid,
+          };
+          continue;
+        }
+
+        if (suggestions.length > 0) {
+          nextSuggestions[index] = {
+            loading: false,
+            suggestions,
+            error: '',
+          };
+        }
+      } catch (error) {
+        nextSuggestions[index] = {
+          loading: false,
+          suggestions: [],
+          error: error instanceof Error ? error.message : 'ORCID search failed.',
+        };
+      }
     }
 
-    downloadFile('.zenodo.json', zenodoPreview, 'application/json;charset=utf-8');
-    setDownloadNotice({
-      kind: 'success',
-      message: 'Citation metadata generated. .zenodo.json is ready and export checks passed.',
-    });
+    return {
+      form: {
+        ...nextForm,
+        authors: nextAuthors,
+      },
+      suggestions: nextSuggestions,
+    };
   }
 
-  async function handleImportRepository() {
-    const trimmedUrl = githubImportUrl.trim();
+  async function handleImportGithubMetadata() {
+    const repoUrl = githubUrl.trim();
 
-    if (!trimmedUrl) {
-      setImportStatus({ state: 'error', message: 'Enter a GitHub repository URL to import metadata.', step: 0 });
+    if (!repoUrl) {
+      setImportStatus({
+        loading: false,
+        warnings: [],
+        review: null,
+        healthScan: [],
+        comparisons: [],
+        errors: [{ kind: 'error', source: 'ui', code: 'empty-url', message: 'Paste a GitHub repository URL first.' }],
+      });
       return;
     }
 
-    if (!isGithubRepositoryUrl(trimmedUrl)) {
+    setImportStatus({ loading: true, warnings: [], errors: [], review: null, healthScan: [], comparisons: [] });
+    const requestId = importRequestIdRef.current + 1;
+    importRequestIdRef.current = requestId;
+
+    try {
+      const result = await importGithubMetadata(repoUrl, {
+        contributorFallbackLimit: 5,
+      });
+
+      if (importRequestIdRef.current !== requestId) {
+        return;
+      }
+
+      let nextForm = metadataToForm(result.metadata);
+      let nextSuggestions = {};
+
+      if (result.errors.length === 0) {
+        const resolved = await resolveOrcidSuggestionsForAuthors(nextForm);
+        nextForm = resolved.form;
+        nextSuggestions = resolved.suggestions;
+      }
+
+      if (importRequestIdRef.current !== requestId) {
+        return;
+      }
+
       setImportStatus({
-        state: 'error',
-        message: 'Use a valid GitHub URL like https://github.com/user/project.',
-        step: 0,
+        loading: false,
+        warnings: result.warnings,
+        errors: result.errors,
+        review: result.review || null,
+        healthScan: Array.isArray(result.healthScan) ? result.healthScan : [],
+        comparisons: Array.isArray(result.comparisons) ? result.comparisons : [],
+      });
+
+      if (result.errors.length === 0) {
+        setForm(nextForm);
+        setOrcidSuggestions(nextSuggestions);
+      }
+    } catch (error) {
+      if (importRequestIdRef.current !== requestId) {
+        return;
+      }
+
+      setImportStatus({
+        loading: false,
+        warnings: [],
+        review: null,
+        healthScan: [],
+        comparisons: [],
+        errors: [{
+          kind: 'error',
+          source: 'import',
+          code: 'import-failed',
+          message: error instanceof Error ? error.message : 'GitHub import failed unexpectedly.',
+        }],
       });
-      return;
     }
+  }
+
+  async function suggestOrcid(index) {
+    const author = form.authors[index] ?? {};
 
-    setImportStatus({ state: 'loading', message: 'Fetching repository metadata...', step: 1 });
-    await wait(240);
-    setImportStatus({ state: 'loading', message: 'Repository found.', step: 1 });
-    await wait(240);
-    setImportStatus({ state: 'loading', message: 'Processing contributors...', step: 2 });
-    await wait(240);
-    setImportStatus({ state: 'loading', message: 'Generating citation defaults...', step: 3 });
-    await wait(240);
+    setOrcidSuggestions((current) => ({
+      ...current,
+      [index]: { loading: true, suggestions: [], error: '' },
+    }));
 
-    const repositoryLabel = parseRepositoryLabel(trimmedUrl);
-    const repositoryName = repositoryLabel.split('/')[1] ?? '';
+    try {
+      const suggestions = await searchOrcidCandidates(author);
+      setOrcidSuggestions((current) => ({
+        ...current,
+        [index]: {
+          loading: false,
+          suggestions,
+          error: suggestions.length > 0 ? '' : 'No ORCID candidates found.',
+        },
+      }));
+    } catch (error) {
+      setOrcidSuggestions((current) => ({
+        ...current,
+        [index]: {
+          loading: false,
+          suggestions: [],
+          error: error instanceof Error ? error.message : 'ORCID search failed.',
+        },
+      }));
+    }
+  }
 
+  function applySuggestedOrcid(index, candidate) {
     setForm((current) => ({
       ...current,
-      repositoryCode: trimmedUrl,
-      title: current.title || repositoryName,
+      authors: current.authors.map((author, i) => {
+        if (i !== index) {
+          return author;
+        }
+
+        return {
+          ...author,
+          orcid: candidate.orcid,
+        };
+      }),
     }));
 
-    setImportStatus({
-      state: 'success',
-      message: repositoryLabel
-        ? `Imported repository context for ${repositoryLabel}. Review metadata and export when ready.`
-        : 'Repository imported. Review metadata and export when ready.',
-      step: 4,
-    });
+    setOrcidSuggestions((current) => ({
+      ...current,
+      [index]: {
+        loading: false,
+        suggestions: [],
+        error: '',
+      },
+    }));
+  }
+
+  function handleDownloadCitation() {
+    if (Object.keys(validationErrors).length > 0) {
+      showValidationNotice(validationErrors);
+      return;
+    }
+
+    if (!citationValidation.isValid) {
+      setExportNotice({
+        kind: 'validation',
+        message: 'Cannot export CITATION.cff until validation issues are fixed.',
+        details: citationValidation.errors,
+      });
+      return;
+    }
+
+    if (!confirmMissingCitationReferences(citationPreview)) {
+      return;
+    }
+
+    clearExportNotice();
+    setIsDownloadingCitation(true);
+    downloadCitationFile();
+    setTimeout(() => {
+      setIsDownloadingCitation(false);
+    }, 500);
+  }
+
+  async function handleDownloadZenodo() {
+    if (Object.keys(validationErrors).length > 0) {
+      showValidationNotice(validationErrors);
+      return;
+    }
+
+    if (!zenodoValidation.isValid) {
+      setExportNotice({
+        kind: 'validation',
+        message: 'Cannot export .zenodo.json until validation issues are fixed.',
+        details: zenodoValidation.errors,
+      });
+      return;
+    }
+
+    clearExportNotice();
+    setIsDownloadingZenodo(true);
+
+    try {
+      await downloadZenodoFile();
+    } finally {
+      setTimeout(() => setIsDownloadingZenodo(false), 500);
+    }
+  }
+
+  async function handleDownloadZip() {
+    if (Object.keys(validationErrors).length > 0) {
+      showValidationNotice(validationErrors);
+      return;
+    }
+
+    if (!citationValidation.isValid) {
+      setExportNotice({
+        kind: 'validation',
+        message: 'Cannot create ZIP until CITATION.cff validation issues are fixed.',
+        details: citationValidation.errors,
+      });
+      return;
+    }
+
+    if (!zenodoValidation.isValid) {
+      setExportNotice({
+        kind: 'validation',
+        message: 'Cannot create ZIP until .zenodo.json validation issues are fixed.',
+        details: zenodoValidation.errors,
+      });
+      return;
+    }
+
+    if (!confirmMissingCitationReferences(citationPreview)) {
+      return;
+    }
+
+    clearExportNotice();
+    setIsZipping(true);
+
+    try {
+      const zipBlob = await createMetadataZipBlob(
+        citationPreview,
+        zenodoPreview,
+        metadataValidationReport,
+      );
+      const safeTitle = String(normalizedForm.title || 'opencite-metadata')
+      .trim()
+      .toLowerCase()
+      .replace(/[^a-z0-9-]+/g, '-')
+      .replace(/^-+|-+$/g, '') || 'opencite-metadata';
+
+      if (canUseNativeFilePicker()) {
+        const saved = await saveFileWithPicker(
+          `${safeTitle}.zip`,
+          zipBlob,
+          'application/zip',
+          [{ description: 'OpenCite metadata ZIP', accept: { 'application/zip': ['.zip'] } }],
+        );
+
+        if (saved) {
+          return;
+        }
+      }
+
+      downloadFile(`${safeTitle}.zip`, zipBlob, 'application/zip');
+    } catch (error) {
+      alert(`Could not create ZIP file: ${error instanceof Error ? error.message : String(error)}`);
+    } finally {
+      setIsZipping(false);
+    }
   }
 
-  function toggleTheme() {
-    setTheme((current) => (current === 'light' ? 'dark' : 'light'));
+  async function handleCopyPreview() {
+    if (copyState !== 'idle') {
+      return;
+    }
+
+    const previewText = previewType === 'citation' ? citationPreview : zenodoPreview;
+
+    try {
+      setCopyState('copying');
+
+      if (!navigator?.clipboard?.writeText) {
+        throw new Error('Clipboard API is unavailable in this browser context.');
+      }
+
+      await navigator.clipboard.writeText(previewText);
+      setCopyState('copied');
+    } catch (error) {
+      console.error('Could not copy preview to clipboard:', error);
+      setCopyState('error');
+    } finally {
+      setTimeout(() => {
+        setCopyState('idle');
+      }, 2000);
+    }
   }
 
   return (
     <main className="app-shell">
       <section className="card">
         <div className="hero">
-          <div className="hero-header">
-            <p className="eyebrow">OpenCite</p>
-            <button
-              type="button"
-              className="secondary theme-toggle"
-              onClick={toggleTheme}
-              aria-label={`Switch to ${theme === 'light' ? 'dark' : 'light'} mode`}
-              title={`Switch to ${theme === 'light' ? 'dark' : 'light'} mode`}
-            >
-              <span aria-hidden="true">{theme === 'light' ? '☾' : '☀'}</span>
-            </button>
-          </div>
-          <h1>Generate citation metadata from one clean form.</h1>
+          <p className="eyebrow">OpenCite</p>
+          <h1>{activePage === 'generator' ? 'Generate citation metadata from one clean form.' : 'Run a citation health review for any GitHub repository.'}</h1>
           <p className="lede">
-            Fill in the metadata once, then download both <strong>CITATION.cff</strong> and
-            <strong>.zenodo.json</strong>.
+            {activePage === 'generator'
+              ? (
+                <>
+                  Fill in the metadata once, then download both <strong>CITATION.cff</strong> and
+                  <strong> .zenodo.json</strong>.
+                </>
+              )
+              : 'Analyze existing repository metadata and get actionable recommendations before deciding what to update or regenerate.'}
           </p>
+        </div>
+
+        <div className="page-tabs" role="tablist" aria-label="OpenCite pages">
           <button
             type="button"
-            className="hero-import"
-            onClick={() => document.getElementById('github-import-url')?.focus()}
+            role="tab"
+            aria-selected={activePage === 'generator'}
+            className={activePage === 'generator' ? 'tab-active' : 'secondary'}
+            onClick={() => setActivePage('generator')}
           >
-            Import GitHub Repository
+            Metadata Generator
+          </button>
+          <button
+            type="button"
+            role="tab"
+            aria-selected={activePage === 'review'}
+            className={activePage === 'review' ? 'tab-active' : 'secondary'}
+            onClick={() => setActivePage('review')}
+          >
+            Citation Health Review
           </button>
         </div>
 
-        <section className="import-panel" aria-labelledby="github-import-title">
-          <div className="import-panel-header">
-            <span className="icon-badge" aria-hidden="true">↗</span>
-            <div>
-              <h2 id="github-import-title">Import from GitHub</h2>
-              <p>
-                Paste a repository URL to automatically generate citation metadata.
-              </p>
+        <section className="learn-more-panel" aria-label="Citation and release resources">
+          <h2>Learn More</h2>
+          <p>
+            Reference these guides while preparing release metadata and citation files.
+          </p>
+          <ul>
+            <li>
+              <a
+                href="https://force11.org/info/software-citation-principles/"
+                target="_blank"
+                rel="noreferrer"
+              >
+                Software citation practices (FORCE11 principles)
+              </a>
+            </li>
+            <li>
+              <a
+                href="https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository"
+                target="_blank"
+                rel="noreferrer"
+              >
+                GitHub release workflow
+              </a>
+            </li>
+            <li>
+              <a
+                href="https://help.zenodo.org/docs/github/"
+                target="_blank"
+                rel="noreferrer"
+              >
+                Zenodo GitHub integration guide
+              </a>
+            </li>
+            <li>
+              <a
+                href="https://github.com/citation-file-format/citation-file-format/blob/main/schema-guide.md"
+                target="_blank"
+                rel="noreferrer"
+              >
+                Citation File Format schema guide
+              </a>
+            </li>
+          </ul>
+        </section>
+
+        {activePage === 'generator' && exportNotice.kind === 'validation' && (
+          <div className="export-notice export-notice-warning" role="alert" aria-live="polite">
+            <strong>{exportNotice.message}</strong>
+            {exportNotice.details.length > 0 && (
+              <ul>
+                {exportNotice.details.slice(0, 5).map((detail, index) => (
+                  <li key={`${detail}-${index}`}>{detail}</li>
+                ))}
+              </ul>
+            )}
+          </div>
+        )}
+
+        {activePage === 'generator' && importStatus.healthScan.length > 0 && (
+          <div className="export-notice export-notice-info" role="status" aria-live="polite">
+            <strong>Reviewed metadata loaded in editor.</strong>
+            <ul>
+              <li>Done well: {healthScanSummary.pass}</li>
+              <li>Needs attention: {healthScanSummary.warning}</li>
+              <li>Errors: {healthScanSummary.error}</li>
+            </ul>
+          </div>
+        )}
+
+        {activePage === 'generator' && (
+          <div className="import-panel compact-import full-width">
+            <label>
+              <span>Import metadata from GitHub repository</span>
+              <input
+                value={githubUrl}
+                onChange={(event) => setGithubUrl(event.target.value)}
+                placeholder="https://github.com/imageomics/OpenCite"
+              />
+            </label>
+            <p className="import-note">
+              This works even when the repository does not have a <strong>CITATION.cff</strong> file.
+            </p>
+            <div className="actions">
+              <button type="button" onClick={handleImportGithubMetadata} disabled={importStatus.loading}>
+                {importStatus.loading ? 'Importing…' : 'Import GitHub metadata'}
+              </button>
+              <button type="button" className="secondary" onClick={() => setActivePage('review')}>
+                Open Full Citation Review
+              </button>
             </div>
+            {(importStatus.errors.length > 0 || importStatus.warnings.length > 0) && (
+              <div className="import-feedback">
+                {importStatus.errors.length > 0 && (
+                  <div className="feedback-block feedback-error">
+                    <strong>Import errors</strong>
+                    <ul>
+                      {importStatus.errors.map((entry, index) => (
+                        <li key={`generator-error-${entry.code}-${index}`}>{entry.message}</li>
+                      ))}
+                    </ul>
+                  </div>
+                )}
+                {importStatus.warnings.length > 0 && (
+                  <div className="feedback-block feedback-warning">
+                    <strong>Import warnings</strong>
+                    <ul>
+                      {warningDisplayList.map((message, index) => (
+                        <li key={`generator-warning-${index}`}>{message}</li>
+                      ))}
+                    </ul>
+                  </div>
+                )}
+              </div>
+            )}
           </div>
-          <label htmlFor="github-import-url" className="full-width">
-            <span>Repository URL</span>
+        )}
+
+        {activePage === 'review' && (
+          <div className="import-panel full-width">
+          <label>
+            <span>Import from GitHub repository</span>
             <input
-              id="github-import-url"
-              name="githubImportUrl"
-              value={githubImportUrl}
-              onChange={(event) => setGithubImportUrl(event.target.value)}
-              placeholder="https://github.com/user/project"
-              aria-describedby="github-import-example"
+              value={githubUrl}
+              onChange={(event) => setGithubUrl(event.target.value)}
+              placeholder="https://github.com/imageomics/OpenCite"
             />
           </label>
-          <small id="github-import-example" className="import-example">Example: https://github.com/user/project</small>
-          <button
-            type="button"
-            className="import-button"
-            onClick={handleImportRepository}
-            disabled={importStatus.state === 'loading'}
-            aria-busy={importStatus.state === 'loading'}
-          >
-            {importStatus.state === 'loading' ? 'Importing repository...' : 'Import Repository'}
-          </button>
-          <p className={`import-status status-${importStatus.state}`} role="status" aria-live="polite">
-            {importStatus.message}
-          </p>
-        </section>
+          <div className="actions">
+            <button type="button" onClick={handleImportGithubMetadata} disabled={importStatus.loading}>
+              {importStatus.loading ? 'Importing…' : 'Import GitHub metadata'}
+            </button>
+          </div>
+          {(importStatus.errors.length > 0 || importStatus.warnings.length > 0 || importStatus.review || importStatus.healthScan.length > 0 || importStatus.comparisons.length > 0) && (
+            <div className="import-feedback">
+              <div className="feedback-block feedback-summary">
+                <strong>Citation Review</strong>
+                <p className="review-summary">
+                  {importReviewSummary.healthy
+                    ? '✓ Repository metadata looks healthy'
+                    : `Warnings (${importReviewSummary.warningCount})`}
+                </p>
+                {importReviewSummary.warnings.length > 0 && (
+                  <ul>
+                    {importReviewSummary.warnings.map((item, index) => (
+                      <li key={`summary-warning-${index}`}>{item}</li>
+                    ))}
+                  </ul>
+                )}
+                {importReviewSummary.recommendations.length > 0 && (
+                  <>
+                    <p className="review-summary">Recommendations</p>
+                    <ul>
+                      {importReviewSummary.recommendations.map((item, index) => (
+                        <li key={`summary-recommendation-${index}`}>{item}</li>
+                      ))}
+                    </ul>
+                  </>
+                )}
+              </div>
+              {importStatus.errors.length > 0 && (
+                <div className="feedback-block feedback-error">
+                  <strong>Import errors</strong>
+                  <ul>
+                    {importStatus.errors.map((entry, index) => (
+                      <li key={`error-${entry.code}-${index}`}>{entry.message}</li>
+                    ))}
+                  </ul>
+                </div>
+              )}
+              {importStatus.warnings.length > 0 && (
+                <div className="feedback-block feedback-warning">
+                  <strong>Import warnings</strong>
+                  <ul>
+                    {warningDisplayList.map((message, index) => (
+                      <li key={`warning-group-${index}`}>{message}</li>
+                    ))}
+                  </ul>
+                </div>
+              )}
+              {importStatus.review && (
+                <div className="feedback-block feedback-review">
+                  <strong>Metadata review</strong>
+                  <p className="review-summary">
+                    Correct: {importStatus.review.summary?.byStatus?.correct ?? 0} | Missing: {importStatus.review.summary?.byStatus?.missing ?? 0} | Outdated: {importStatus.review.summary?.byStatus?.outdated ?? 0} | Invalid: {importStatus.review.summary?.byStatus?.invalid ?? 0}
+                  </p>
+                  {Array.isArray(importStatus.review.recommendations?.actions) && importStatus.review.recommendations.actions.length > 0 && (
+                    <ul>
+                      {importStatus.review.recommendations.actions.map((action, index) => (
+                        <li key={`review-action-${index}`}>{action}</li>
+                      ))}
+                    </ul>
+                  )}
+                  {Array.isArray(importStatus.review.findings) && importStatus.review.findings.length > 0 && (
+                    <ul>
+                      {importStatus.review.findings.map((finding, index) => (
+                        <li key={`review-finding-${finding.id || index}`}>
+                          [{formatReviewStatus(finding.status)} | {formatReviewAction(finding.action)}]
+                          {finding.file ? ` ${finding.file}:` : ''} {finding.message}
+                        </li>
+                      ))}
+                    </ul>
+                  )}
+                </div>
+              )}
+              {importStatus.healthScan.length > 0 && (
+                <div className="feedback-block feedback-health">
+                  <strong>Citation health scan</strong>
+                  <p className="review-summary">
+                    Done well: {healthScanSummary.pass} | Needs attention: {healthScanSummary.warning} | Errors: {healthScanSummary.error}
+                  </p>
+                  <div className="actions">
+                    <button type="button" onClick={openReviewedMetadataInGenerator}>
+                      Open Reviewed Metadata In Editor
+                    </button>
+                  </div>
 
-        <section className="pipeline-card" aria-labelledby="pipeline-title">
-          <h2 id="pipeline-title">Pipeline</h2>
-          <ol className="pipeline-list">
-            {PIPELINE_STEPS.map((label, index) => {
-              const stepNumber = index + 1;
-              const state = stepNumber < currentPipelineStep
-                ? 'complete'
-                : stepNumber === currentPipelineStep
-                  ? 'current'
-                  : 'upcoming';
-
-              return (
-                <li key={label} className={`pipeline-step pipeline-step-${state}`}>
-                  <span className="step-badge" aria-hidden="true">{stepNumber}</span>
-                  <span>{label}</span>
-                </li>
-              );
-            })}
-          </ol>
-        </section>
+                  {healthErrorChecks.length > 0 && (
+                    <div className="health-group">
+                      <h3>Errors (Fix first)</h3>
+                      <ul className="health-list">
+                        {healthErrorChecks.map((check, index) => renderHealthCheckCard(check, `health-error-${index}`))}
+                      </ul>
+                    </div>
+                  )}
 
-        <MetadataForm
-          form={form}
-          typeOptions={typeOptions}
-          licenseOptions={licenseOptions}
-          updateField={updateField}
-          updateAuthorField={updateAuthorField}
-          addAuthor={addAuthor}
-          removeAuthor={removeAuthor}
-        />
-
-        <div className="actions">
-          <button type="button" onClick={handleDownloadCitation}>
-            Generate CITATION.cff
-          </button>
-          <button type="button" className="secondary" onClick={handleDownloadZenodo}>
-            Generate .zenodo.json
-          </button>
-        </div>
+                  {healthWarningChecks.length > 0 && (
+                    <div className="health-group">
+                      <h3>Warnings (Recommended updates)</h3>
+                      <ul className="health-list">
+                        {healthWarningChecks.map((check, index) => renderHealthCheckCard(check, `health-warning-${index}`))}
+                      </ul>
+                    </div>
+                  )}
 
-        {downloadNotice.message ? (
-          <div className={`notice-card notice-${downloadNotice.kind}`} role="status" aria-live="polite">
-            <p className="notice-title">✓ Citation metadata generated</p>
-            <p>{downloadNotice.message}</p>
-            <p className="notice-files">Ready: CITATION.cff and .zenodo.json</p>
+                  {healthPassChecks.length > 0 && (
+                    <div className="health-group">
+                      <h3>Done Well</h3>
+                      <ul className="health-list">
+                        {healthPassChecks.map((check, index) => renderHealthCheckCard(check, `health-pass-${index}`))}
+                      </ul>
+                    </div>
+                  )}
+                </div>
+              )}
+              {importStatus.comparisons.length > 0 && (
+                <div className="feedback-block feedback-comparison">
+                  <strong>Field-by-field comparison (existing files vs live GitHub metadata)</strong>
+                  <ul className="comparison-list">
+                    {importStatus.comparisons.map((item, index) => (
+                      <li key={`comparison-${item.file}-${item.field}-${index}`} className="comparison-item">
+                        <div className="comparison-header">
+                          <strong>{item.file} - {item.field}</strong>
+                          <span className="comparison-status">{formatComparisonStatus(item.status)}</span>
+                        </div>
+                        <p><span>Current:</span> {item.currentValue || '(missing)'}</p>
+                        <p><span>GitHub:</span> {item.githubValue || '(cannot determine)'}</p>
+                        <p><span>Recommendation:</span> {item.recommendation}</p>
+                      </li>
+                    ))}
+                  </ul>
+                </div>
+              )}
+            </div>
+          )}
           </div>
-        ) : null}
+        )}
 
-        <section className="metadata-cards" aria-label="Metadata overview">
-          <article className="metadata-card">
-            <h3>Repository Information</h3>
-            <p><strong>Name:</strong> {normalizedForm.title || 'Pending'}</p>
-            <p><strong>URL:</strong> {normalizedForm.repositoryCode || 'Not set'}</p>
-          </article>
-          <article className="metadata-card">
-            <h3>Authors</h3>
-            <p><strong>Count:</strong> {authorSummary.length}</p>
-            <p>{authorSummary.length > 0 ? authorSummary.slice(0, 3).join(' • ') : 'No authors added yet'}</p>
-          </article>
-          <article className="metadata-card">
-            <h3>Version & License</h3>
-            <p><strong>Version:</strong> {normalizedForm.version || 'Not set'}</p>
-            <p><strong>License:</strong> {normalizedForm.license || 'Not set'}</p>
-          </article>
-          <article className="metadata-card">
-            <h3>Citation Files</h3>
-            <p>CITATION.cff</p>
-            <p>.zenodo.json</p>
-          </article>
-        </section>
+        {activePage === 'generator' && (
+          <>
+            <MetadataForm
+              form={form}
+              typeOptions={typeOptions}
+              licenseOptions={licenseOptions}
+              grantSuggestions={grantSuggestions}
+              errors={validationErrors}
+              orcidSuggestions={orcidSuggestions}
+              updateField={updateField}
+              appendGrantSuggestion={appendGrantSuggestion}
+              appendAllGrantSuggestions={appendAllGrantSuggestions}
+              updateAuthorField={updateAuthorField}
+              suggestOrcid={suggestOrcid}
+              applySuggestedOrcid={applySuggestedOrcid}
+              reorderAuthor={reorderAuthor}
+              addAuthor={addAuthor}
+              removeAuthor={removeAuthor}
+            />
 
-        <div className="preview">
-          <div>
-            <h2>Preview</h2>
             <div className="actions">
               <button
                 type="button"
-                className={previewType === 'citation' ? '' : 'secondary'}
-                onClick={() => setPreviewType('citation')}
+                onClick={handleDownloadCitation}
+                disabled={isDownloadingCitation}
+                className={isDownloadingCitation ? 'loading-button' : ''}
               >
-                CITATION.cff
+                {isDownloadingCitation && <span className="button-spinner" aria-hidden="true" />}
+                {isDownloadingCitation ? 'Generating CITATION.cff…' : 'Generate CITATION.cff'}
               </button>
               <button
                 type="button"
-                className={previewType === 'zenodo' ? '' : 'secondary'}
-                onClick={() => setPreviewType('zenodo')}
+                className={`secondary ${isDownloadingZenodo ? 'loading-button' : ''}`}
+                onClick={handleDownloadZenodo}
+                disabled={isDownloadingZenodo}
               >
-                .zenodo.json
+                {isDownloadingZenodo && <span className="button-spinner" aria-hidden="true" />}
+                {isDownloadingZenodo ? 'Generating .zenodo.json…' : 'Generate .zenodo.json'}
+              </button>
+              <button
+                type="button"
+                className={`secondary ${isZipping ? 'loading-button' : ''}`}
+                onClick={handleDownloadZip}
+                disabled={isZipping}
+              >
+                {isZipping && <span className="button-spinner" aria-hidden="true" />}
+                {isZipping ? 'Creating ZIP…' : 'Download ZIP (Both Files)'}
               </button>
             </div>
-            <pre>{previewType === 'citation' ? citationPreview : zenodoPreview}</pre>
-          </div>
-        </div>
+            <p className="filename-note">
+              Keep the Zenodo filename as <strong>.zenodo.json</strong> for downstream tooling compatibility. The ZIP now includes <strong>METADATA_VALIDATION.txt</strong> with export checks.
+            </p>
 
-        <footer className="app-footer" aria-label="Project acknowledgements">
-          <h3>About OpenCite</h3>
-          <p>
-            OpenCite helps researchers create standardized citation metadata for research software.
-          </p>
-          <p>
-            This work was supported by both the{' '}
-            <a href="https://imageomics.org/" target="_blank" rel="noreferrer">Imageomics Institute</a>
-            {' '}and the{' '}
-            <a href="http://abcresearchcenter.org/" target="_blank" rel="noreferrer">AI and Biodiversity Change (ABC) Global Center</a>
-            . The Imageomics Institute is funded by the U.S. National Science Foundation&apos;s Harnessing the Data Revolution (HDR) program under{' '}
-            <a href="https://www.nsf.gov/awardsearch/showAward?AWD_ID=2118240" target="_blank" rel="noreferrer">Award #2118240</a>
-            {' '}(Imageomics: A New Frontier of Biological Information Powered by Knowledge-Guided Machine Learning). The ABC Global Center is funded by the U.S. National Science Foundation under{' '}
-            <a href="https://www.nsf.gov/awardsearch/showAward?AWD_ID=2330423&amp;HistoricalAwards=false" target="_blank" rel="noreferrer">Award No. 2330423</a>
-            {' '}and Natural Sciences and Engineering Research Council of Canada under{' '}
-            <a href="https://www.nserc-crsng.gc.ca/ase-oro/Details-Detailles_eng.asp?id=782440" target="_blank" rel="noreferrer">Award No. 585136</a>
-            . This work draws on research supported by the Social Sciences and Humanities Research Council. Any opinions, findings and conclusions or recommendations expressed in this material are those of the author(s) and do not necessarily reflect the views of the National Science Foundation, Natural Sciences and Engineering Research Council of Canada, or Social Sciences and Humanities Research Council.
-          </p>
-          <p>
-            Contributors: Isabella Lo and Elizabeth Campolongo.
-          </p>
-          <p>
-            <a href="https://github.com/Imageomics/OpenCite" target="_blank" rel="noreferrer">
-              View OpenCite on GitHub
-            </a>
-            {' • '}
-            <a href="https://github.com/Imageomics/OpenCite/blob/main/CITATION.cff" target="_blank" rel="noreferrer">
-              Cite this project
-            </a>
-            {' • '}
-            <a href="https://imageomics.github.io/Collaborative-distributed-science-guide/" target="_blank" rel="noreferrer">
-              Read the Collaborative Distributed Science Guide
-            </a>
-          </p>
-        </footer>
+            <div className="preview">
+              <div>
+                <h2>Preview</h2>
+                <div className="actions">
+                  <button
+                    type="button"
+                    className={previewType === 'citation' ? '' : 'secondary'}
+                    onClick={() => setPreviewType('citation')}
+                  >
+                    CITATION.cff
+                  </button>
+                  <button
+                    type="button"
+                    className={previewType === 'zenodo' ? '' : 'secondary'}
+                    onClick={() => setPreviewType('zenodo')}
+                  >
+                    .zenodo.json
+                  </button>
+                  <button
+                    type="button"
+                    className="secondary"
+                    onClick={handleCopyPreview}
+                    disabled={copyState !== 'idle'}
+                  >
+                    {copyState === 'copied'
+                      ? '✓ Copied!'
+                      : copyState === 'error'
+                        ? 'Copy failed'
+                        : copyState === 'copying'
+                          ? 'Copying...'
+                          : 'Copy'}
+                  </button>
+                </div>
+                <pre>{previewType === 'citation' ? citationPreview : zenodoPreview}</pre>
+              </div>
+            </div>
+          </>
+        )}
       </section>
     </main>
   );
diff --git a/src/components/MetadataForm.jsx b/src/components/MetadataForm.jsx
index e10aa89..da40dee 100644
--- a/src/components/MetadataForm.jsx
+++ b/src/components/MetadataForm.jsx
@@ -1,164 +1,392 @@
+import { useState } from 'react';
+
 export function MetadataForm({
   form,
   typeOptions,
   licenseOptions,
+  grantSuggestions = [],
+  errors = {},
+  orcidSuggestions = {},
   updateField,
+  appendGrantSuggestion,
+  appendAllGrantSuggestions,
   updateAuthorField,
+  suggestOrcid,
+  applySuggestedOrcid,
+  reorderAuthor,
   addAuthor,
   removeAuthor,
 }) {
+  const AUTHORS_VISIBLE_BY_DEFAULT = 3;
+  const [showAllAuthors, setShowAllAuthors] = useState(false);
+  const [expandedAuthors, setExpandedAuthors] = useState({});
+
+  const totalAuthors = Array.isArray(form.authors) ? form.authors.length : 0;
+  const visibleAuthorCount = showAllAuthors ? totalAuthors : Math.min(totalAuthors, AUTHORS_VISIBLE_BY_DEFAULT);
+  const hiddenAuthorCount = Math.max(0, totalAuthors - visibleAuthorCount);
+
+  function toggleAuthorExpanded(index) {
+    setExpandedAuthors((current) => ({
+      ...current,
+      [index]: !current[index],
+    }));
+  }
+
   return (
     <form className="form-grid" onSubmit={(event) => event.preventDefault()}>
-      <label className="full-width">
-        <span>Title</span>
-        <input name="title" value={form.title} onChange={updateField} placeholder="Project title" />
-      </label>
-
-      <label className="full-width">
-        <span>Authors</span>
-        <div className="authors-list">
-          {form.authors.map((author, index) => (
-            <div key={author.id ?? `author-${index}`} className="author-row">
-              <input
-                value={author.givenNames}
-                onChange={(event) => updateAuthorField(index, 'givenNames', event.target.value)}
-                placeholder="Given names"
-              />
-              <input
-                value={author.familyNames}
-                onChange={(event) => updateAuthorField(index, 'familyNames', event.target.value)}
-                placeholder="Family names"
-              />
-              <input
-                value={author.orcid}
-                onChange={(event) => updateAuthorField(index, 'orcid', event.target.value)}
-                placeholder="ORCID (optional)"
-              />
-              <input
-                value={author.affiliation}
-                onChange={(event) => updateAuthorField(index, 'affiliation', event.target.value)}
-                placeholder="Affiliation (optional)"
-              />
-              <button type="button" className="secondary" onClick={() => removeAuthor(index)}>
-                Remove author
+      <p className="full-width required-note">* required for valid metadata export</p>
+
+      <section className="full-width form-section" aria-labelledby="section-basics-title">
+        <header className="section-header">
+          <p className="section-step">1. Basics</p>
+          <h3 id="section-basics-title">Core project details</h3>
+          <p className="section-lede">Start with what this work is and how people should reference it.</p>
+        </header>
+        <div className="section-grid">
+          <label className={`full-width ${errors.title ? 'field-error' : ''}`}>
+            <span>Title*</span>
+            <input
+              className={errors.title ? 'input-error' : ''}
+              name="title"
+              value={form.title}
+              onChange={updateField}
+              placeholder="Project title"
+              aria-invalid={Boolean(errors.title)}
+            />
+            {errors.title ? <small className="error-text">{errors.title}</small> : null}
+          </label>
+
+          <label className="full-width">
+            <span>Abstract</span>
+            <textarea
+              name="abstract"
+              value={form.abstract}
+              onChange={updateField}
+              rows="6"
+              placeholder="Short description of the work"
+            />
+          </label>
+        </div>
+      </section>
+
+      <section className="full-width form-section" aria-labelledby="section-authors-title">
+        <header className="section-header">
+          <p className="section-step">2. Creators</p>
+          <h3 id="section-authors-title">Author list and ORCID</h3>
+          <p className="section-lede">Add authors in publication order, then enrich with ORCID and affiliation.</p>
+        </header>
+        <label className={`full-width ${errors.authors ? 'field-error' : ''}`}>
+          <span>Authors*</span>
+          {totalAuthors > AUTHORS_VISIBLE_BY_DEFAULT && (
+            <div className="authors-toolbar">
+              <small>
+                Showing {visibleAuthorCount} of {totalAuthors} author{totalAuthors === 1 ? '' : 's'}.
+              </small>
+              <button
+                type="button"
+                className="secondary"
+                onClick={() => setShowAllAuthors((current) => !current)}
+              >
+                {showAllAuthors ? `Show fewer authors` : `Show all authors (${totalAuthors})`}
               </button>
             </div>
-          ))}
+          )}
+          <div className="authors-list">
+            {form.authors.slice(0, visibleAuthorCount).map((author, index) => {
+              const displayName = [author.givenNames, author.familyNames].filter(Boolean).join(' ').trim() || `Author ${index + 1}`;
+              const hasOrcidError = Boolean(errors.authorOrcid?.[index]);
+              const shouldExpandByDefault = showAllAuthors || index < AUTHORS_VISIBLE_BY_DEFAULT || hasOrcidError;
+              const isExpanded = Object.prototype.hasOwnProperty.call(expandedAuthors, index)
+                ? expandedAuthors[index]
+                : shouldExpandByDefault;
+
+              return (
+                <div key={author.id ?? `author-${index}`} className="author-row">
+                  <div className="author-row-header">
+                    <strong>{displayName}</strong>
+                    <button
+                      type="button"
+                      className="secondary"
+                      onClick={() => toggleAuthorExpanded(index)}
+                    >
+                      {isExpanded ? 'Hide details' : 'Show details'}
+                    </button>
+                  </div>
+
+                  {isExpanded && (
+                    <>
+                      <input
+                        value={author.givenNames}
+                        onChange={(event) => updateAuthorField(index, 'givenNames', event.target.value)}
+                        placeholder="Given names"
+                      />
+                      <input
+                        value={author.familyNames}
+                        onChange={(event) => updateAuthorField(index, 'familyNames', event.target.value)}
+                        placeholder="Family names"
+                      />
+                      <input
+                        value={author.orcid}
+                        onChange={(event) => updateAuthorField(index, 'orcid', event.target.value)}
+                        placeholder="ORCID (optional)"
+                        className={errors.authorOrcid?.[index] ? 'input-error' : ''}
+                        aria-invalid={Boolean(errors.authorOrcid?.[index])}
+                      />
+                      {errors.authorOrcid?.[index] ? <small className="error-text">{errors.authorOrcid[index]}</small> : null}
+                      <div className="orcid-tools">
+                        <button
+                          type="button"
+                          className="secondary"
+                          onClick={() => suggestOrcid(index)}
+                          disabled={orcidSuggestions[index]?.loading}
+                        >
+                          {orcidSuggestions[index]?.loading ? 'Searching…' : 'Suggest ORCID'}
+                        </button>
+                        {orcidSuggestions[index]?.error ? <small className="error-text">{orcidSuggestions[index].error}</small> : null}
+                        {orcidSuggestions[index]?.suggestions?.length > 0 ? (
+                          <div className="orcid-suggestions">
+                            {orcidSuggestions[index].suggestions.map((candidate) => (
+                              <button
+                                key={`${candidate.orcid}-${candidate.label}`}
+                                type="button"
+                                className="secondary orcid-suggestion"
+                                onClick={() => applySuggestedOrcid(index, candidate)}
+                              >
+                                {candidate.label} - {candidate.orcid.replace('https://orcid.org/', '')}
+                              </button>
+                            ))}
+                          </div>
+                        ) : null}
+                      </div>
+                      <input
+                        value={author.affiliation}
+                        onChange={(event) => updateAuthorField(index, 'affiliation', event.target.value)}
+                        placeholder="Affiliation (optional)"
+                      />
+                      <div className="author-actions">
+                        <button
+                          type="button"
+                          className="secondary icon-button"
+                          onClick={() => reorderAuthor(index, -1)}
+                          disabled={index === 0}
+                          aria-label={`Move author ${index + 1} up`}
+                          title="Move up"
+                        >
+                          ↑
+                        </button>
+                        <button
+                          type="button"
+                          className="secondary icon-button"
+                          onClick={() => reorderAuthor(index, 1)}
+                          disabled={index === form.authors.length - 1}
+                          aria-label={`Move author ${index + 1} down`}
+                          title="Move down"
+                        >
+                          ↓
+                        </button>
+                        <button type="button" className="secondary" onClick={() => removeAuthor(index)}>
+                          Remove author
+                        </button>
+                      </div>
+                    </>
+                  )}
+                </div>
+              );
+            })}
+          </div>
+          {hiddenAuthorCount > 0 && !showAllAuthors && (
+            <small>
+              {hiddenAuthorCount} more author{hiddenAuthorCount === 1 ? '' : 's'} hidden. Use "Show all authors" to manage the full list.
+            </small>
+          )}
+          <button type="button" className="secondary" onClick={addAuthor}>
+            Add author
+          </button>
+          {errors.authors ? <small className="error-text">{errors.authors}</small> : null}
+        </label>
+      </section>
+
+      <section className="full-width form-section" aria-labelledby="section-publishing-title">
+        <header className="section-header">
+          <p className="section-step">3. Publishing metadata</p>
+          <h3 id="section-publishing-title">Version, date, license, and identifiers</h3>
+          <p className="section-lede">Use release-aligned values so your exports match what users see on GitHub and Zenodo.</p>
+        </header>
+        <div className="section-grid">
+          <label className={errors.typeOfWork ? 'field-error' : ''}>
+            <span>Type of work*</span>
+            <select
+              className={errors.typeOfWork ? 'input-error' : ''}
+              name="typeOfWork"
+              value={form.typeOfWork}
+              onChange={updateField}
+              aria-invalid={Boolean(errors.typeOfWork)}
+            >
+              {typeOptions.map((option) => (
+                <option key={option.value} value={option.value}>
+                  {option.label}
+                </option>
+              ))}
+            </select>
+            {errors.typeOfWork ? <small className="error-text">{errors.typeOfWork}</small> : null}
+          </label>
+
+          {form.typeOfWork === 'other' && (
+            <label>
+              <span>Specify type of work</span>
+              <input
+                name="customTypeOfWork"
+                value={form.customTypeOfWork}
+                onChange={updateField}
+                placeholder="e.g., protocol, poster, thesis"
+              />
+            </label>
+          )}
+
+          <label className={errors.version ? 'field-error' : ''}>
+            <span>Version*</span>
+            <input
+              className={errors.version ? 'input-error' : ''}
+              name="version"
+              value={form.version}
+              onChange={updateField}
+              placeholder="e.g. v1.2.3 or 1.2.3"
+              aria-invalid={Boolean(errors.version)}
+            />
+            <small>Use Semantic Versioning (MAJOR.MINOR.PATCH), like <strong>1.2.3</strong> or <strong>v1.2.3</strong>. Use the exact value you plan to publish as your GitHub release tag.</small>
+            <small>
+              Need a refresher? See
+              {' '}
+              <a href="https://semver.org/" target="_blank" rel="noreferrer">semver.org</a>
+              .
+            </small>
+            {errors.version ? <small className="error-text">{errors.version}</small> : null}
+          </label>
+
+          <label className={errors.publicationDate ? 'field-error' : ''}>
+            <span>Publication date</span>
+            <input
+              className={errors.publicationDate ? 'input-error' : ''}
+              name="publicationDate"
+              value={form.publicationDate}
+              onChange={updateField}
+              placeholder="YYYY-MM-DD"
+              aria-invalid={Boolean(errors.publicationDate)}
+            />
+            {errors.publicationDate ? <small className="error-text">{errors.publicationDate}</small> : null}
+          </label>
+
+          <label className={errors.license ? 'field-error' : ''}>
+            <span>License*</span>
+            <select
+              className={errors.license ? 'input-error' : ''}
+              name="license"
+              value={form.license}
+              onChange={updateField}
+              aria-invalid={Boolean(errors.license)}
+            >
+              <option value="">Select license (SPDX code)</option>
+              {licenseOptions.map((license) => (
+                <option key={license} value={license}>
+                  {license}
+                </option>
+              ))}
+            </select>
+            {errors.license ? <small className="error-text">{errors.license}</small> : null}
+          </label>
+
+          <label>
+            <span>Repository URL</span>
+            <input
+              name="repositoryCode"
+              value={form.repositoryCode}
+              onChange={updateField}
+              placeholder="https://github.com/user/repo"
+            />
+          </label>
+
+          <label>
+            <span>DOI (version-agnostic, from Zenodo)</span>
+            <input name="doi" value={form.doi} onChange={updateField} placeholder="10.0000/zenodo.example.doi" />
+          </label>
+
+          <label>
+            <span>Keywords</span>
+            <input
+              name="keywords"
+              value={form.keywords}
+              onChange={updateField}
+              placeholder="open science, metadata, citation"
+            />
+          </label>
         </div>
-        <button type="button" className="secondary" onClick={addAuthor}>
-          Add author
-        </button>
-      </label>
-
-      <label>
-        <span>License</span>
-        <select name="license" value={form.license} onChange={updateField}>
-          <option value="">Select license (SPDX code)</option>
-          {licenseOptions.map((license) => (
-            <option key={license} value={license}>
-              {license}
-            </option>
-          ))}
-        </select>
-      </label>
-
-      <label>
-        <span>Keywords</span>
-        <input
-          name="keywords"
-          value={form.keywords}
-          onChange={updateField}
-          placeholder="open science, metadata, citation"
-        />
-      </label>
-
-      <label>
-        <span>Type of work</span>
-        <select name="typeOfWork" value={form.typeOfWork} onChange={updateField}>
-          {typeOptions.map((option) => (
-            <option key={option.value} value={option.value}>
-              {option.label}
-            </option>
-          ))}
-        </select>
-      </label>
-
-      {form.typeOfWork === 'other' && (
-        <label>
-          <span>Specify type of work</span>
-          <input
-            name="customTypeOfWork"
-            value={form.customTypeOfWork}
+      </section>
+
+      <section className="full-width form-section" aria-labelledby="section-references-title">
+        <header className="section-header">
+          <p className="section-step">4. References</p>
+          <h3 id="section-references-title">Related work and dependencies</h3>
+        </header>
+        <label className="full-width">
+          <span>References</span>
+          <textarea
+            name="references"
+            value={form.references}
+            onChange={updateField}
+            rows="8"
+            placeholder={"One citation per line\n\nOr structured blocks separated by blank lines, for example:\n- type: software\ntitle: Example software title\nversion: 1.0.0\nauthors:\n  - family-names: Lastname\n    given-names: Firstname\nrepository-code: https://github.com/org/repo\ndate-released: 2025-01-01\ndoi: 10.0000/example\nlicense: MIT"}
+          />
+          <small>Use one plain-text citation per line, or use structured key:value blocks (separated by blank lines) for full Citation.cff references.</small>
+        </label>
+      </section>
+
+      <section className="full-width form-section" aria-labelledby="section-funding-title">
+        <header className="section-header">
+          <p className="section-step">5. Funding</p>
+          <h3 id="section-funding-title">Grant IDs and acknowledgements</h3>
+        </header>
+        <label className={`full-width ${errors.grants ? 'field-error' : ''}`}>
+          <span>Grants</span>
+          <textarea
+            className={errors.grants ? 'input-error' : ''}
+            name="grants"
+            value={form.grants}
             onChange={updateField}
-            placeholder="e.g., protocol, poster, thesis"
+            rows="3"
+            placeholder="One grant ID per line"
+            aria-invalid={Boolean(errors.grants)}
           />
+          <div className="grant-suggestions">
+            {grantSuggestions.map((grant) => (
+              <button
+                key={grant.id}
+                type="button"
+                className="secondary"
+                title={grant.note}
+                onClick={() => appendGrantSuggestion(grant.id)}
+              >
+                Add {grant.label}
+              </button>
+            ))}
+            <button type="button" className="secondary" onClick={appendAllGrantSuggestions}>
+              Add all suggested grants
+            </button>
+          </div>
+          <ul className="grant-reference-list">
+            {grantSuggestions.map((grant) => (
+              <li key={`reference-${grant.id}`}>
+                <strong>{grant.id}</strong>
+                {' '}
+                -
+                {' '}
+                {grant.note}
+              </li>
+            ))}
+          </ul>
+          <small>Format: &lt;funder-code&gt;::&lt;grant-number&gt; (e.g., 021nxhr62::2118240)</small>
+          {errors.grants ? <small className="error-text">{errors.grants}</small> : null}
         </label>
-      )}
-
-      <label>
-        <span>Version</span>
-        <input name="version" value={form.version} onChange={updateField} placeholder="1.0.0" />
-      </label>
-
-      <label>
-        <span>Publication date</span>
-        <input
-          name="publicationDate"
-          value={form.publicationDate}
-          onChange={updateField}
-          placeholder="YYYY-MM-DD"
-        />
-      </label>
-
-      <label>
-        <span>Repository URL</span>
-        <input
-          name="repositoryCode"
-          value={form.repositoryCode}
-          onChange={updateField}
-          placeholder="https://github.com/user/repo"
-        />
-      </label>
-
-      <label>
-        <span>DOI (version-agnostic, from Zenodo)</span>
-        <input name="doi" value={form.doi} onChange={updateField} placeholder="10.0000/zenodo.example.doi" />
-      </label>
-
-      <label className="full-width">
-        <span>Abstract</span>
-        <textarea
-          name="abstract"
-          value={form.abstract}
-          onChange={updateField}
-          rows="6"
-          placeholder="Short description of the work"
-        />
-      </label>
-
-      <label className="full-width">
-        <span>References</span>
-        <textarea
-          name="references"
-          value={form.references}
-          onChange={updateField}
-          rows="4"
-          placeholder="One citation per line"
-        />
-        <small>One reference per line. Plain text citation format.</small>
-      </label>
-
-      <label className="full-width">
-        <span>Grants</span>
-        <textarea
-          name="grants"
-          value={form.grants}
-          onChange={updateField}
-          rows="3"
-          placeholder="One grant ID per line"
-        />
-        <small>Format: &lt;funder-code&gt;::&lt;grant-number&gt; (e.g., 021nxhr62::2118240)</small>
-      </label>
+      </section>
     </form>
   );
 }
diff --git a/src/services/citation.js b/src/services/citation.js
index 363e5b7..aa5b3d0 100644
--- a/src/services/citation.js
+++ b/src/services/citation.js
@@ -11,12 +11,151 @@ function indentBlock(value) {
     .join('\n');
 }
 
+function sanitizeCffType(value, fallback = 'article') {
+  const raw = String(value ?? '').trim();
+  if (!raw) {
+    return fallback;
+  }
+
+  // Strip inline explanatory comments, e.g. "software (python package)".
+  const withoutParens = raw.replace(/\s*\([^)]*\)\s*$/g, '').trim();
+  const token = withoutParens.toLowerCase().split(/\s+/)[0] || '';
+  const normalized = token.replace(/[^a-z0-9-]/g, '');
+
+  return normalized || fallback;
+}
+
+function sanitizeReferenceTitle(value) {
+  return String(value ?? '').replace(/\s+/g, ' ').trim();
+}
+
+function toCitationReferenceEntry(reference) {
+  if (reference && typeof reference === 'object' && !Array.isArray(reference)) {
+    const type = sanitizeCffType(reference.type, 'article');
+    const normalizedTitle = String(reference.title || reference.reference || reference.text || '').trim();
+    const normalizedVersion = String(reference.version || '').trim();
+    const normalizedRepositoryCode = String(reference['repository-code'] || '').trim();
+    const normalizedDateReleased = String(reference['date-released'] || '').trim();
+    const normalizedDoi = String(reference.doi || '').trim();
+    const normalizedLicense = String(reference.license || '').trim();
+    const normalizedUrl = String(reference.url || '').trim();
+
+    const hasScalarContent = Boolean(normalizedTitle || normalizedDoi || normalizedUrl);
+
+    const normalizedAuthors = Array.isArray(reference.authors)
+      ? reference.authors
+        .filter((author) => author && typeof author === 'object')
+        .map((author) => ({
+          familyNames: String(author['family-names'] ?? '').trim(),
+          givenNames: String(author['given-names'] ?? '').trim(),
+          orcid: String(author.orcid ?? '').trim(),
+        }))
+        .filter((author) => author.familyNames || author.givenNames || author.orcid)
+      : [];
+
+    if (!hasScalarContent) {
+      return [];
+    }
+
+    const title = sanitizeReferenceTitle(
+      normalizedTitle
+      || (normalizedDoi ? `DOI: ${normalizedDoi}` : '')
+      || (normalizedUrl ? `URL: ${normalizedUrl}` : ''),
+    );
+
+    if (!title) {
+      return [];
+    }
+
+    const lines = [`  - type: ${quoteYAML(type)}`];
+
+    lines.push(`    title: "${quoteYAML(title)}"`);
+
+    if (normalizedDoi) {
+      lines.push(`    doi: ${quoteYAML(normalizedDoi)}`);
+    }
+    if (normalizedUrl) {
+      lines.push(`    url: "${quoteYAML(normalizedUrl)}"`);
+    }
+
+    if (normalizedVersion) {
+      lines.push(`    version: "${quoteYAML(normalizedVersion)}"`);
+    }
+    if (normalizedRepositoryCode) {
+      lines.push(`    repository-code: "${quoteYAML(normalizedRepositoryCode)}"`);
+    }
+    if (normalizedDateReleased) {
+      lines.push(`    date-released: "${quoteYAML(normalizedDateReleased)}"`);
+    }
+    if (normalizedLicense) {
+      lines.push(`    license: "${quoteYAML(normalizedLicense)}"`);
+    }
+
+    if (normalizedAuthors.length > 0) {
+      lines.push('    authors:');
+
+      for (const author of normalizedAuthors) {
+        const familyNames = author.familyNames;
+        const givenNames = author.givenNames;
+        const orcid = author.orcid;
+        let authorLine = '      -';
+
+        if (familyNames) {
+          authorLine += ` family-names: "${quoteYAML(familyNames)}"`;
+        }
+
+        if (givenNames) {
+          authorLine += authorLine === '      -'
+            ? ` given-names: "${quoteYAML(givenNames)}"`
+            : `\n        given-names: "${quoteYAML(givenNames)}"`;
+        }
+
+        lines.push(authorLine);
+        if (orcid) {
+          lines.push(`        orcid: "${quoteYAML(orcid)}"`);
+        }
+      }
+    }
+
+    return lines;
+  }
+
+  const text = String(reference ?? '').trim();
+  if (!text) {
+    return [];
+  }
+
+  const doiMatch = text.match(/(?:https?:\/\/(?:dx\.)?doi\.org\/|doi:\s*)(10\.\d{4,9}\/[\w./;():-]+)/i);
+  if (doiMatch) {
+    const doi = doiMatch[1].replace(/[.,;:]+$/g, '');
+    return [
+      '  - type: article',
+      `    title: "${quoteYAML(sanitizeReferenceTitle(text))}"`,
+      `    doi: ${quoteYAML(doi)}`,
+      `    url: "${quoteYAML(`https://doi.org/${doi}`)}"`,
+    ];
+  }
+
+  if (/^https?:\/\//i.test(text)) {
+    return [
+      '  - type: article',
+      `    title: "${quoteYAML(sanitizeReferenceTitle(text))}"`,
+      `    url: "${quoteYAML(text)}"`,
+    ];
+  }
+
+  return [
+    '  - type: article',
+    `    title: "${quoteYAML(sanitizeReferenceTitle(text))}"`,
+  ];
+}
+
 export function toCitationCff(metadata) {
-  const typeOfWork = metadata.typeOfWork || 'software';
+  const typeOfWork = sanitizeCffType(metadata.typeOfWork, 'software');
   const repositoryCode = metadata.repositoryCode || 'https://github.com/Imageomics/repository';
-  const releaseTag = metadata.version || 'v0.0.0';
-  const releaseUrl = `${repositoryCode}/releases/tag/${releaseTag}`;
-  const commitTreeUrl = `${repositoryCode}/tree/${releaseTag}`;
+  const releaseTag = String(metadata.version ?? '').trim();
+  const releaseUrl = releaseTag ? `${repositoryCode}/releases/tag/${releaseTag}` : '';
+  const taggedTreeUrl = releaseTag ? `${repositoryCode}/tree/${releaseTag}` : '';
   const authors = metadata.authors.map((author) => {
     const lines = [
       `- family-names: "${quoteYAML(author.citationAuthor['family-names'])}"`,
@@ -35,7 +174,13 @@ export function toCitationCff(metadata) {
   const keywords = keywordsWithDefault.map(
     (keyword) => `  - "${quoteYAML(keyword)}"`,
   );
+  const references = (Array.isArray(metadata.references) ? metadata.references : [])
+    .flatMap((reference) => toCitationReferenceEntry(reference));
   const abstractText = metadata.abstract || 'No abstract provided.';
+  const hasReferences = Array.isArray(metadata.references) && metadata.references.length > 0;
+  const citationMessage = hasReferences
+    ? 'If you find this work helpful in your research, please cite this work and the associated references.'
+    : 'If you find this work helpful in your research, please cite it.';
 
   return [
     'abstract: >-',
@@ -46,17 +191,22 @@ export function toCitationCff(metadata) {
       : ['- family-names: "Unknown"', '  given-names: "Author"', '  orcid: "https://orcid.org/0000-0000-0000-0000"']),
     'cff-version: 1.2.0',
     `date-released: "${quoteYAML(metadata.publicationDate || 'YYYY-MM-DD')}"`,
-    'identifiers:',
-    `  - description: "The GitHub release URL of tag ${quoteYAML(releaseTag)}."`,
-    '    type: url',
-    `    value: "${quoteYAML(releaseUrl)}"`,
-    `  - description: "The GitHub URL of the commit tagged with ${quoteYAML(releaseTag)}."`,
-    '    type: url',
-    `    value: "${quoteYAML(commitTreeUrl)}"`,
+    ...(releaseUrl
+      ? [
+          'identifiers:',
+          `  - description: "The GitHub release URL of tag ${quoteYAML(releaseTag)}."`,
+          '    type: url',
+          `    value: "${quoteYAML(releaseUrl)}"`,
+          `  - description: "The GitHub source tree URL aligned to release tag ${quoteYAML(releaseTag)}."`,
+          '    type: url',
+          `    value: "${quoteYAML(taggedTreeUrl)}"`,
+        ]
+      : []),
     'keywords:',
     ...keywords,
+    ...(references.length > 0 ? ['references:', ...references] : []),
     `license: "${quoteYAML(metadata.license)}"`,
-    'message: "If you find this software helpful in your research, please cite both the software and our paper."',
+    `message: "${quoteYAML(citationMessage)}"`,
     `repository-code: "${quoteYAML(repositoryCode)}"`,
     `title: "${quoteYAML(metadata.title)}"`,
     `version: "${quoteYAML(metadata.version)}"`,
diff --git a/src/services/citationHealthScan.js b/src/services/citationHealthScan.js
new file mode 100644
index 0000000..f7538b5
--- /dev/null
+++ b/src/services/citationHealthScan.js
@@ -0,0 +1,526 @@
+import { isValidOrcidFormat } from '../utils/orcid.js';
+
+function cleanString(value) {
+  return String(value ?? '').trim();
+}
+
+function normalizeDate(value) {
+  return cleanString(value).split('T')[0];
+}
+
+function normalizeVersion(value) {
+  return cleanString(value).toLowerCase().replace(/^v(?=\d)/, '');
+}
+
+function parseSemver(value) {
+  const normalized = normalizeVersion(value);
+  const match = normalized.match(/^(\d+)\.(\d+)\.(\d+)(?:-([0-9a-z]+(?:\.[0-9a-z]+)*))?(?:\+[0-9a-z]+(?:\.[0-9a-z]+)*)?$/i);
+
+  if (!match) {
+    return null;
+  }
+
+  return {
+    major: Number(match[1]),
+    minor: Number(match[2]),
+    patch: Number(match[3]),
+    prerelease: match[4] ?? '',
+  };
+}
+
+function comparePrerelease(left, right) {
+  const leftParts = left ? left.split('.') : [];
+  const rightParts = right ? right.split('.') : [];
+
+  if (leftParts.length === 0 && rightParts.length === 0) {
+    return 0;
+  }
+
+  if (leftParts.length === 0) {
+    return 1;
+  }
+
+  if (rightParts.length === 0) {
+    return -1;
+  }
+
+  const limit = Math.max(leftParts.length, rightParts.length);
+
+  for (let index = 0; index < limit; index += 1) {
+    const leftPart = leftParts[index];
+    const rightPart = rightParts[index];
+
+    if (leftPart == null) {
+      return -1;
+    }
+
+    if (rightPart == null) {
+      return 1;
+    }
+
+    const leftNumeric = /^\d+$/.test(leftPart);
+    const rightNumeric = /^\d+$/.test(rightPart);
+
+    if (leftNumeric && rightNumeric) {
+      const diff = Number(leftPart) - Number(rightPart);
+      if (diff !== 0) {
+        return diff;
+      }
+      continue;
+    }
+
+    if (leftNumeric && !rightNumeric) {
+      return -1;
+    }
+
+    if (!leftNumeric && rightNumeric) {
+      return 1;
+    }
+
+    if (leftPart < rightPart) {
+      return -1;
+    }
+
+    if (leftPart > rightPart) {
+      return 1;
+    }
+  }
+
+  return 0;
+}
+
+function compareSemver(left, right) {
+  if (left.major !== right.major) {
+    return left.major - right.major;
+  }
+
+  if (left.minor !== right.minor) {
+    return left.minor - right.minor;
+  }
+
+  if (left.patch !== right.patch) {
+    return left.patch - right.patch;
+  }
+
+  return comparePrerelease(left.prerelease, right.prerelease);
+}
+
+function normalizeRepoUrl(value) {
+  return cleanString(value)
+    .replace(/^git\+/, '')
+    .replace(/\/+$/, '')
+    .replace(/\.git$/i, '')
+    .replace(/\/+$/, '')
+    .toLowerCase();
+}
+
+function normalizeLicense(value) {
+  return cleanString(value)
+    .toUpperCase()
+    .replace(/^SPDX:/, '')
+    .trim();
+}
+
+function buildCheck(status, title, description, recommendation) {
+  return {
+    status,
+    title,
+    description,
+    recommendation,
+  };
+}
+
+function checkCitationFile(context) {
+  const citation = context.fileValidationSummary?.citation;
+
+  if (citation?.present) {
+    if (citation.valid) {
+      return buildCheck(
+        'pass',
+        'Repository has a CITATION.cff',
+        'CITATION.cff was found and passed schema validation.',
+        'Keep the file and update only changed fields when needed.',
+      );
+    }
+
+    return buildCheck(
+      'error',
+      'Repository has a CITATION.cff',
+      `CITATION.cff exists but is invalid: ${(citation.errors || []).join(' | ')}`,
+      'Fix required fields or regenerate CITATION.cff before trusting imported values.',
+    );
+  }
+
+  return buildCheck(
+    'warning',
+    'Repository is missing a CITATION.cff',
+    'No CITATION.cff file was found in the repository.',
+    'Generate a CITATION.cff file to improve citation metadata quality.',
+  );
+}
+
+function checkZenodoFile(context) {
+  const zenodo = context.fileValidationSummary?.zenodo;
+
+  if (zenodo?.present) {
+    if (zenodo.valid) {
+      return buildCheck(
+        'pass',
+        'Repository has a .zenodo.json',
+        '.zenodo.json was found and passed schema validation.',
+        'Keep the file and update only changed fields when needed.',
+      );
+    }
+
+    return buildCheck(
+      'error',
+      'Repository has a .zenodo.json',
+      `.zenodo.json exists but is invalid: ${(zenodo.errors || []).join(' | ')}`,
+      'Fix required fields or regenerate .zenodo.json before trusting imported values.',
+    );
+  }
+
+  return buildCheck(
+    'warning',
+    'Repository is missing a .zenodo.json',
+    'No .zenodo.json file was found in the repository.',
+    'Generate a .zenodo.json file for Zenodo-compatible metadata exports.',
+  );
+}
+
+function checkRepositoryUrlCurrent(context) {
+  const repoUrl = normalizeRepoUrl(context.repoData?.html_url);
+  const metadataRepoUrl = normalizeRepoUrl(context.metadata?.repositoryCode);
+
+  if (!repoUrl && !metadataRepoUrl) {
+    return buildCheck(
+      'warning',
+      'Repository URL is current',
+      'Repository URL metadata is not available for comparison.',
+      'Set repository-code to the canonical GitHub repository URL.',
+    );
+  }
+
+  if (repoUrl && !metadataRepoUrl) {
+    return buildCheck(
+      'warning',
+      'Repository URL is current',
+      'Repository URL is available, but repository-code is missing from imported metadata.',
+      'Set repository-code to the canonical GitHub repository URL.',
+    );
+  }
+
+  if (!repoUrl && metadataRepoUrl) {
+    return buildCheck(
+      'warning',
+      'Repository URL is current',
+      'Repository URL could not be verified from GitHub API data.',
+      'Verify repository-code manually and rerun import when GitHub API access is available.',
+    );
+  }
+
+  if (repoUrl && metadataRepoUrl && repoUrl !== metadataRepoUrl) {
+    return buildCheck(
+      'warning',
+      'Repository URL is current',
+      'Imported repository URL does not match the current repository URL.',
+      'Update repository-code to match the current GitHub repository URL.',
+    );
+  }
+
+  return buildCheck(
+    'pass',
+    'Repository URL is current',
+    'Repository URL metadata matches the current repository URL.',
+    'Keep repository URL updated after transfers or renames.',
+  );
+}
+
+function checkVersionMatchesRelease(context) {
+  const releaseTag = cleanString(context.releaseData?.tag_name);
+  const version = cleanString(context.metadata?.version);
+  const releaseSemver = parseSemver(releaseTag);
+  const metadataSemver = parseSemver(version);
+
+  if (!version) {
+    return buildCheck(
+      'error',
+      'Version is ahead of latest release tag',
+      'Version metadata is missing.',
+      'Set a semantic version for the upcoming release metadata.',
+    );
+  }
+
+  if (!metadataSemver) {
+    return buildCheck(
+      'warning',
+      'Version is ahead of latest release tag',
+      `Version metadata (${version}) is not parseable as semantic versioning.`,
+      'Use semantic version format (for example 1.2.3) for upcoming-release metadata.',
+    );
+  }
+
+  if (!releaseTag) {
+    return buildCheck(
+      'pass',
+      'Version is ahead of latest release tag',
+      'No latest release tag is available, so there is no baseline to compare; metadata version is accepted for the planned upcoming release.',
+      'Keep semantic versioning for planned releases; progression checks will apply once a baseline release exists.',
+    );
+  }
+
+  if (!releaseSemver) {
+    return buildCheck(
+      'warning',
+      'Version is ahead of latest release tag',
+      `Latest release tag (${releaseTag}) is not parseable as semantic versioning.`,
+      'Use semantic version release tags (for example v1.2.3) so upcoming-release progression can be validated.',
+    );
+  }
+
+  if (compareSemver(metadataSemver, releaseSemver) <= 0) {
+    return buildCheck(
+      'warning',
+      'Version is ahead of latest release tag',
+      `Version metadata (${version}) is not ahead of the latest release tag (${releaseTag}).`,
+      'Set metadata version to the next logical semantic version for the upcoming release.',
+    );
+  }
+
+  return buildCheck(
+    'pass',
+    'Version is ahead of latest release tag',
+    `Version metadata (${version}) is a valid next semantic version relative to latest release (${releaseTag}).`,
+    'Keep metadata version ahead of the latest release while preparing the next release.',
+  );
+}
+
+function checkReleaseDateMatchesRelease(context) {
+  const releaseDate = normalizeDate(context.releaseData?.published_at);
+  const metadataDate = normalizeDate(context.metadata?.publicationDate);
+
+  if (!metadataDate) {
+    return buildCheck(
+      'warning',
+      'Publication date is after latest release date',
+      'Publication date metadata is missing.',
+      'Set publication date for the planned upcoming release.',
+    );
+  }
+
+  if (!releaseDate) {
+    return buildCheck(
+      'pass',
+      'Publication date is after latest release date',
+      'No latest release publish date is available, so there is no baseline to compare; metadata publication date is accepted for the planned upcoming release.',
+      'Keep publication date current for the planned release; progression checks will apply once a baseline release exists.',
+    );
+  }
+
+  if (releaseDate && metadataDate && metadataDate <= releaseDate) {
+    return buildCheck(
+      'warning',
+      'Publication date is after latest release date',
+      `Metadata publication date (${metadataDate}) is not later than latest release date (${releaseDate}).`,
+      'Set publication date for a newer upcoming release timeline.',
+    );
+  }
+
+  return buildCheck(
+    'pass',
+    'Publication date is after latest release date',
+    `Publication date metadata (${metadataDate}) is later than latest release date (${releaseDate}).`,
+    'Keep publication date current for the next planned release.',
+  );
+}
+
+function checkLicenseMatchesRepository(context) {
+  const repositoryLicense = normalizeLicense(context.repoData?.license?.spdx_id);
+  const metadataLicense = normalizeLicense(context.metadata?.license);
+
+  if (!repositoryLicense && !metadataLicense) {
+    return buildCheck(
+      'warning',
+      'License matches repository license',
+      'Neither repository nor metadata license information is available, so the match cannot be verified.',
+      'Set a clear SPDX license in repository metadata and citation files.',
+    );
+  }
+
+  if (repositoryLicense && !metadataLicense) {
+    return buildCheck(
+      'warning',
+      'License matches repository license',
+      'Repository license is available, but metadata license is missing, so the match cannot be verified.',
+      'Set metadata license to match repository SPDX license so match verification can be completed.',
+    );
+  }
+
+  if (!repositoryLicense && metadataLicense) {
+    return buildCheck(
+      'warning',
+      'License matches repository license',
+      'Metadata license is present, but repository SPDX license is missing, so the match cannot be verified.',
+      'Add repository SPDX license information and keep metadata aligned with repository policy.',
+    );
+  }
+
+  if (repositoryLicense && metadataLicense && repositoryLicense !== metadataLicense) {
+    return buildCheck(
+      'warning',
+      'License matches repository license',
+      'Metadata license does not align with repository SPDX license.',
+      'Update citation metadata license to match repository license policy.',
+    );
+  }
+
+  return buildCheck(
+    'pass',
+    'License matches repository license',
+    'Metadata license aligns with repository license information.',
+    'Keep license metadata aligned with repository SPDX settings.',
+  );
+}
+
+function checkAuthorsPresent(context) {
+  const authors = Array.isArray(context.metadata?.authors) ? context.metadata.authors : [];
+
+  if (authors.length === 0) {
+    return buildCheck(
+      'error',
+      'Authors are present',
+      'No authors were found in merged metadata.',
+      'Add at least one author to citation metadata before export.',
+    );
+  }
+
+  return buildCheck(
+    'pass',
+    'Authors are present',
+    `${authors.length} author${authors.length === 1 ? '' : 's'} found in metadata.`,
+    'Maintain complete author attribution for each release.',
+  );
+}
+
+function checkOrcidValid(context) {
+  const authors = Array.isArray(context.metadata?.authors) ? context.metadata.authors : [];
+  const authoredOrcids = authors.map((author) => cleanString(author?.orcid)).filter(Boolean);
+  const missingCount = authors.filter((author) => !cleanString(author?.orcid)).length;
+
+  const invalidOrcids = authoredOrcids.filter((orcid) => !isValidOrcidFormat(orcid));
+
+  if (invalidOrcids.length > 0) {
+    return buildCheck(
+      'error',
+      'ORCID IDs are valid',
+      `${invalidOrcids.length} ORCID value${invalidOrcids.length === 1 ? ' is' : 's are'} invalid.`
+      + (missingCount > 0 ? ` Missing ORCID for ${missingCount} author${missingCount === 1 ? '' : 's'}.` : ''),
+      'Correct ORCID format/checksum for all listed ORCID identifiers and add missing ORCIDs when available.',
+    );
+  }
+
+  if (authoredOrcids.length === 0) {
+    return buildCheck(
+      'warning',
+      'ORCID IDs are valid',
+      missingCount > 0
+        ? `Missing ORCID for ${missingCount} author${missingCount === 1 ? '' : 's'}.`
+        : 'No ORCID IDs were provided for authors.',
+      'Add ORCID IDs for contributors when available to improve author disambiguation.',
+    );
+  }
+
+  if (missingCount > 0) {
+    return buildCheck(
+      'warning',
+      'ORCID IDs are valid',
+      `Missing ORCID for ${missingCount} author${missingCount === 1 ? '' : 's'}.`,
+      'Add ORCID IDs for contributors when available to improve author disambiguation.',
+    );
+  }
+
+  return buildCheck(
+    'pass',
+    'ORCID IDs are valid',
+    'All provided ORCID IDs are valid.',
+    'Keep ORCID IDs updated for ongoing contributor attribution.',
+  );
+}
+
+function checkKeywordsExist(context) {
+  const keywords = Array.isArray(context.metadata?.keywords) ? context.metadata.keywords.filter(Boolean) : [];
+
+  if (keywords.length === 0) {
+    return buildCheck(
+      'warning',
+      'Keywords exist',
+      'No keywords were found in metadata.',
+      'Add project keywords to improve discoverability in citation systems.',
+    );
+  }
+
+  return buildCheck(
+    'pass',
+    'Keywords exist',
+    `${keywords.length} keyword${keywords.length === 1 ? '' : 's'} found in metadata.`,
+    'Keep keywords focused and current with project scope.',
+  );
+}
+
+function checkAbstractExists(context) {
+  const abstract = cleanString(context.metadata?.abstract);
+
+  if (!abstract) {
+    return buildCheck(
+      'warning',
+      'Abstract exists',
+      'No abstract/description was found in metadata.',
+      'Add a concise abstract describing purpose and scope of the project.',
+    );
+  }
+
+  return buildCheck(
+    'pass',
+    'Abstract exists',
+    'Abstract/description is present in metadata.',
+    'Keep abstract up to date as project goals evolve.',
+  );
+}
+
+function checkDoiExistsWhenExpected(context) {
+  const doi = cleanString(context.metadata?.doi);
+
+  if (doi) {
+    return buildCheck(
+      'pass',
+      'Project DOI is available',
+      'Version-agnostic project DOI is present in citation metadata.',
+      'Keep using the version-agnostic project DOI in citation metadata; version-specific release DOIs are handled separately by the archive/release workflow.',
+    );
+  }
+
+  return buildCheck(
+    'pass',
+    'Project DOI is available',
+    'A DOI is not required for this citation workflow.',
+    'If a project DOI is available, include the version-agnostic project DOI in citation metadata; do not require a version-specific release DOI in CITATION.cff.',
+  );
+}
+
+export const defaultCitationHealthChecks = [
+  checkCitationFile,
+  checkZenodoFile,
+  checkRepositoryUrlCurrent,
+  checkVersionMatchesRelease,
+  checkReleaseDateMatchesRelease,
+  checkLicenseMatchesRepository,
+  checkAuthorsPresent,
+  checkOrcidValid,
+  checkKeywordsExist,
+  checkAbstractExists,
+  checkDoiExistsWhenExpected,
+];
+
+export function runCitationHealthScan(context, checks = defaultCitationHealthChecks) {
+  return checks.map((check) => check(context));
+}
diff --git a/src/services/citationValidation.js b/src/services/citationValidation.js
new file mode 100644
index 0000000..3d7d021
--- /dev/null
+++ b/src/services/citationValidation.js
@@ -0,0 +1,169 @@
+function cleanString(value) {
+  return String(value ?? '').trim();
+}
+
+function isValidIsoDate(value) {
+  const text = cleanString(value);
+  if (!text || !/^\d{4}-\d{2}-\d{2}$/.test(text)) {
+    return false;
+  }
+
+  const [yearText, monthText, dayText] = text.split('-');
+  const year = Number(yearText);
+  const month = Number(monthText);
+  const day = Number(dayText);
+
+  if (!Number.isInteger(year) || !Number.isInteger(month) || !Number.isInteger(day)) {
+    return false;
+  }
+
+  const date = new Date(Date.UTC(year, month - 1, day));
+  return date.getUTCFullYear() === year
+    && date.getUTCMonth() === month - 1
+    && date.getUTCDate() === day;
+}
+
+function extractSingleScalar(text, key) {
+  const regex = new RegExp(`^${key}:\\s*(.+)\\s*$`, 'm');
+  const value = cleanString((String(text).match(regex) || [])[1]);
+
+  if (!value) {
+    return '';
+  }
+
+  const quotedMatch = value.match(/^"(.*)"$/) || value.match(/^'(.*)'$/);
+  return cleanString(quotedMatch ? quotedMatch[1] : value);
+}
+
+function hasAuthorsArrayWithEntry(text) {
+  const lines = String(text ?? '').split(/\r?\n/);
+  const authorsIndex = lines.findIndex((line) => /^authors:\s*(.*)$/.test(line));
+
+  if (authorsIndex < 0) {
+    return false;
+  }
+
+  const authorsLineMatch = lines[authorsIndex].match(/^authors:\s*(.*)$/);
+  const trailing = cleanString(authorsLineMatch ? authorsLineMatch[1] : '');
+
+  if (trailing) {
+    if (/^\[\s*\]$/.test(trailing)) {
+      return false;
+    }
+
+    if (/^\[.*\]$/.test(trailing)) {
+      return cleanString(trailing.slice(1, -1)).length > 0;
+    }
+
+    return false;
+  }
+
+  for (let index = authorsIndex + 1; index < lines.length; index += 1) {
+    const line = lines[index];
+
+    if (/^\S.*?:\s*/.test(line)) {
+      break;
+    }
+
+    if (/^\s+-\s+/.test(line)) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+function formatReport({ isValid, errors, warnings, fields }) {
+  const lines = [
+    'OpenCite Metadata Validation Report',
+    '=================================',
+    `Status: ${isValid ? 'PASS' : 'FAIL'}`,
+    '',
+    'File: CITATION.cff',
+    `Generated: ${new Date().toISOString()}`,
+    '',
+  ];
+
+  if (errors.length > 0) {
+    lines.push('Errors:');
+    for (const error of errors) {
+      lines.push(`- ${error}`);
+    }
+    lines.push('');
+  }
+
+  if (warnings.length > 0) {
+    lines.push('Warnings:');
+    for (const warning of warnings) {
+      lines.push(`- ${warning}`);
+    }
+    lines.push('');
+  }
+
+  lines.push('Summary:');
+  lines.push(`- title: ${fields.title ? 'present' : 'missing'}`);
+  lines.push(`- version: ${fields.version ? fields.version : 'missing'}`);
+  lines.push(`- date-released: ${fields.dateReleased ? fields.dateReleased : 'missing'}`);
+  lines.push(`- repository-code: ${fields.repositoryCode ? 'present' : 'missing'}`);
+
+  return lines.join('\n');
+}
+
+export function validateCitationCffText(text) {
+  const errors = [];
+  const warnings = [];
+  const content = String(text ?? '');
+
+  const cffVersion = extractSingleScalar(content, 'cff-version');
+  const title = extractSingleScalar(content, 'title');
+  const version = extractSingleScalar(content, 'version');
+  const dateReleased = extractSingleScalar(content, 'date-released');
+  const repositoryCode = extractSingleScalar(content, 'repository-code');
+
+  if (!cffVersion) {
+    errors.push('cff-version is required.');
+  }
+
+  if (!title) {
+    errors.push('title is required.');
+  }
+
+  if (!version) {
+    errors.push('version is required.');
+  }
+
+  if (!dateReleased) {
+    errors.push('date-released is required.');
+  } else if (!isValidIsoDate(dateReleased)) {
+    errors.push('date-released must be a real date in YYYY-MM-DD format.');
+  }
+
+  if (!hasAuthorsArrayWithEntry(content)) {
+    errors.push('authors must include at least one author entry.');
+  }
+
+  if (!repositoryCode) {
+    warnings.push('repository-code is recommended for provenance and release linking.');
+  }
+
+  if (!/^https?:\/\//i.test(repositoryCode || '')) {
+    warnings.push('repository-code should be an absolute URL.');
+  }
+
+  const isValid = errors.length === 0;
+  const fields = {
+    title,
+    version,
+    dateReleased,
+    repositoryCode,
+  };
+  const report = formatReport({ isValid, errors, warnings, fields });
+
+  return {
+    isValid,
+    errors,
+    warnings,
+    fields,
+    report,
+  };
+}
diff --git a/src/services/fixtures/invalid.CITATION.cff b/src/services/fixtures/invalid.CITATION.cff
new file mode 100644
index 0000000..4848600
--- /dev/null
+++ b/src/services/fixtures/invalid.CITATION.cff
@@ -0,0 +1,5 @@
+cff-version: 1.2.0
+title: "OpenCite"
+version: "1.2.3"
+date-released: "2026-99-99"
+repository-code: "not-a-url"
diff --git a/src/services/fixtures/invalid.zenodo.json b/src/services/fixtures/invalid.zenodo.json
new file mode 100644
index 0000000..b8b3359
--- /dev/null
+++ b/src/services/fixtures/invalid.zenodo.json
@@ -0,0 +1,14 @@
+{
+  "title": "",
+  "upload_type": "software",
+  "description": "Metadata export utility",
+  "version": "",
+  "publication_date": "2026-77-12",
+  "license": "MIT",
+  "keywords": ["imageomics", "citation"],
+  "creators": [],
+  "grants": [
+    { "id": "bad-grant-format" }
+  ],
+  "references": []
+}
diff --git a/src/services/fixtures/valid.CITATION.cff b/src/services/fixtures/valid.CITATION.cff
new file mode 100644
index 0000000..ffd38ed
--- /dev/null
+++ b/src/services/fixtures/valid.CITATION.cff
@@ -0,0 +1,10 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it."
+title: "OpenCite"
+version: "1.2.3"
+date-released: "2026-07-12"
+repository-code: "https://github.com/Imageomics/OpenCite"
+license: "MIT"
+authors:
+  - family-names: "Doe"
+    given-names: "Jane"
diff --git a/src/services/fixtures/valid.zenodo.json b/src/services/fixtures/valid.zenodo.json
new file mode 100644
index 0000000..6b15d93
--- /dev/null
+++ b/src/services/fixtures/valid.zenodo.json
@@ -0,0 +1,20 @@
+{
+  "title": "OpenCite",
+  "upload_type": "software",
+  "description": "Metadata export utility",
+  "version": "1.2.3",
+  "publication_date": "2026-07-12",
+  "license": "MIT",
+  "keywords": ["imageomics", "citation"],
+  "creators": [
+    {
+      "name": "Jane Doe",
+      "orcid": "",
+      "affiliation": "Imageomics"
+    }
+  ],
+  "grants": [
+    { "id": "021nxhr62::2118240" }
+  ],
+  "references": []
+}
diff --git a/src/services/github.examples.js b/src/services/github.examples.js
index dcd8937..0e03713 100644
--- a/src/services/github.examples.js
+++ b/src/services/github.examples.js
@@ -1,16 +1,14 @@
 /**
  * Example usage of importGithubMetadata
  *
- * This demonstrates how to use the enhanced GitHub metadata importer to populate
- * OpenCite form fields from a GitHub repository. The importer uses GitHub API
- * metadata by default and optionally inspects repository files for additional metadata.
+ * This demonstrates how to use the GitHub metadata importer to populate
+ * OpenCite form fields from a GitHub repository.
  */
 
-import { importGithubMetadata } from '../services/githubImporter.js';
+import { importGithubMetadata } from './githubImporter.js';
 
 /**
- * Example: Default API-only mode
- * Fetches metadata from GitHub API only (fastest, no file inspection).
+ * Example: Fetch metadata from a GitHub repository and populate form
  */
 export async function exampleImportGitHubRepo() {
   try {
@@ -109,7 +107,7 @@ export async function exampleWithMultipleOptions() {
     const { metadata, warnings, errors } = await importGithubMetadata(repoUrl, {
       inspectRepositoryFiles: true,
       contributorFallbackLimit: 8,
-      authToken: import.meta.env?.VITE_GITHUB_TOKEN ?? '',
+      authToken: '',
     });
 
     console.log('Full metadata:', metadata);
diff --git a/src/services/githubApi.js b/src/services/githubApi.js
new file mode 100644
index 0000000..4b55d6c
--- /dev/null
+++ b/src/services/githubApi.js
@@ -0,0 +1,233 @@
+const API_BASE = 'https://api.github.com';
+
+function cleanString(value) {
+  return String(value ?? '').replace(/[\t ]+/g, ' ').trim();
+}
+
+export function parseGithubUrl(repoUrl) {
+  let parsedUrl;
+
+  try {
+    parsedUrl = new URL(repoUrl);
+  } catch {
+    throw new Error('Invalid GitHub repository URL.');
+  }
+
+  const host = parsedUrl.hostname.replace(/^www\./, '').toLowerCase();
+  if (host !== 'github.com') {
+    throw new Error('Only GitHub repository URLs are supported.');
+  }
+
+  const parts = parsedUrl.pathname.split('/').filter(Boolean).map((part) => decodeURIComponent(part));
+  if (parts.length < 2) {
+    throw new Error('Expected a repository URL in the form https://github.com/owner/repo.');
+  }
+
+  const [owner, repoRaw] = parts;
+  return { owner, repo: repoRaw.replace(/\.git$/i, '') };
+}
+
+function encodePath(path) {
+  return String(path)
+    .split('/')
+    .map((segment) => encodeURIComponent(segment))
+    .join('/');
+}
+
+function decodeBase64(content) {
+  const normalized = String(content ?? '').replace(/\s+/g, '');
+
+  if (!normalized) {
+    return '';
+  }
+
+  if (typeof atob === 'function') {
+    const binary = atob(normalized);
+
+    if (typeof TextDecoder === 'function') {
+      const bytes = Uint8Array.from(binary, (char) => char.charCodeAt(0));
+      return new TextDecoder('utf-8').decode(bytes);
+    }
+
+    return binary;
+  }
+
+  if (typeof Buffer !== 'undefined') {
+    return Buffer.from(normalized, 'base64').toString('utf8');
+  }
+
+  return '';
+}
+
+function responseMessage(response, payload) {
+  if (payload && typeof payload === 'object' && payload.message) {
+    return String(payload.message);
+  }
+
+  return `${response.status} ${response.statusText}`.trim();
+}
+
+export function resolveGithubToken(options = {}) {
+  const explicitToken = cleanString(options.authToken ?? '');
+  if (explicitToken) {
+    return explicitToken;
+  }
+
+  try {
+    if (typeof window !== 'undefined' && window.localStorage) {
+      const localToken = cleanString(window.localStorage.getItem('opencite_github_token') ?? '');
+      if (localToken) {
+        return localToken;
+      }
+    }
+  } catch {
+    // localStorage access can fail in restricted browsing contexts.
+  }
+
+  return '';
+}
+
+export function createGithubHeaders(token = '') {
+  const headers = {
+    Accept: 'application/vnd.github+json',
+    'X-GitHub-Api-Version': '2022-11-28',
+  };
+
+  if (token) {
+    headers.Authorization = `Bearer ${token}`;
+  }
+
+  return headers;
+}
+
+export async function fetchJson(url, authToken = '') {
+  let response;
+
+  try {
+    response = await fetch(url, {
+      headers: createGithubHeaders(authToken),
+    });
+  } catch (error) {
+    return {
+      ok: false,
+      status: 0,
+      statusText: 'Network error',
+      data: null,
+      rateLimited: false,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+
+  const text = await response.text();
+  let data = null;
+
+  if (text) {
+    try {
+      data = JSON.parse(text);
+    } catch {
+      data = text;
+    }
+  }
+
+  return {
+    ok: response.ok,
+    status: response.status,
+    statusText: response.statusText,
+    data,
+    rateLimited: response.status === 403 && response.headers.get('x-ratelimit-remaining') === '0',
+  };
+}
+
+export async function fetchRequiredJson(url, { authToken = '', source, onError }) {
+  const result = await fetchJson(url, authToken);
+
+  if (!result.ok) {
+    const message = result.rateLimited
+      ? 'GitHub API rate limit exceeded.'
+      : responseMessage(result, result.data);
+    onError(source, result.rateLimited ? 'rate-limited' : 'request-failed', message, { url });
+    return null;
+  }
+
+  return result.data;
+}
+
+export async function fetchOptionalJson(url, { authToken = '', source, label, onWarning }) {
+  const result = await fetchJson(url, authToken);
+
+  if (!result.ok) {
+    if (result.status === 404) {
+      return null;
+    }
+
+    const message = result.rateLimited
+      ? `GitHub API rate limit exceeded while fetching ${label}.`
+      : `${label} unavailable: ${responseMessage(result, result.data)}`;
+    onWarning(source, result.rateLimited ? 'rate-limited' : 'request-failed', message, { url });
+    return null;
+  }
+
+  return result.data;
+}
+
+export async function fetchLatestCommitDate(owner, repo, defaultBranch, { authToken = '', onWarning }) {
+  const branchFilter = defaultBranch ? `&sha=${encodeURIComponent(defaultBranch)}` : '';
+  const commits = await fetchOptionalJson(
+    `${API_BASE}/repos/${owner}/${repo}/commits?per_page=1${branchFilter}`,
+    {
+      authToken,
+      source: 'commits',
+      label: 'the latest commit',
+      onWarning,
+    },
+  );
+
+  if (!Array.isArray(commits) || commits.length === 0) {
+    return '';
+  }
+
+  return cleanString(commits[0]?.commit?.committer?.date ?? commits[0]?.commit?.author?.date ?? '');
+}
+
+export async function fetchContentsFile(owner, repo, path, ref, { authToken = '', onWarning }) {
+  const url = `${API_BASE}/repos/${owner}/${repo}/contents/${encodePath(path)}?ref=${encodeURIComponent(ref)}`;
+  const result = await fetchJson(url, authToken);
+
+  if (!result.ok) {
+    if (result.status === 404) {
+      return null;
+    }
+
+    onWarning(
+      'contents',
+      result.rateLimited ? 'rate-limited' : 'request-failed',
+      result.rateLimited
+        ? `GitHub API rate limit exceeded while fetching ${path}.`
+        : `Unable to fetch ${path}: ${responseMessage(result, result.data)}`,
+      { path, url },
+    );
+    return null;
+  }
+
+  const payload = result.data;
+  if (!payload || Array.isArray(payload)) {
+    onWarning('contents', 'unexpected-response', `GitHub returned an unexpected payload for ${path}.`, { path, url });
+    return null;
+  }
+
+  if (payload.truncated && payload.download_url) {
+    const rawResult = await fetchJson(payload.download_url, authToken);
+    if (rawResult.ok) {
+      return typeof rawResult.data === 'string' ? rawResult.data : '';
+    }
+
+    onWarning('contents', 'request-failed', `Unable to fetch the full contents of ${path}.`, { path, url });
+    return null;
+  }
+
+  if (payload.encoding === 'base64' && payload.content) {
+    return decodeBase64(payload.content);
+  }
+
+  return '';
+}
\ No newline at end of file
diff --git a/src/services/githubImporter.js b/src/services/githubImporter.js
index d0a47df..a1ac604 100644
--- a/src/services/githubImporter.js
+++ b/src/services/githubImporter.js
@@ -1,12 +1,25 @@
 import { createMetadata } from '../core/metadataModel.js';
-import { normalizeOrcid } from '../utils/orcid.js';
+import { extractOrcidFromGithubHtml, extractOrcidFromGithubProfile, normalizeOrcid } from '../utils/orcid.js';
+import { validateCitationCffText } from './citationValidation.js';
+import { runCitationHealthScan } from './citationHealthScan.js';
+import {
+  fetchContentsFile,
+  fetchLatestCommitDate,
+  fetchOptionalJson,
+  fetchRequiredJson,
+  parseGithubUrl,
+  resolveGithubToken,
+} from './githubApi.js';
+import { compareExistingMetadataFiles } from './metadataComparison.js';
+import { runMetadataReviewPipeline } from './metadataReview.js';
+import { validateZenodoJsonText } from './zenodoValidation.js';
 
 const API_BASE = 'https://api.github.com';
 const TOP_CONTRIBUTOR_FALLBACK_LIMIT = 4;
 const MAX_CONTRIBUTOR_FALLBACK_LIMIT = 20;
+const GITHUB_PAGE_SIZE = 100;
 const FILES_TO_INSPECT = [
   'CITATION.cff',
-  'citation.cff',
   '.zenodo.json',
   'README.md',
   'package.json',
@@ -231,101 +244,29 @@ function normalizeRepoUrl(value) {
     return '';
   }
 
-  return text.replace(/^git\+/, '').replace(/\.git$/i, '');
-}
-
-function parseGithubUrl(repoUrl) {
-  let parsedUrl;
-
-  try {
-    parsedUrl = new URL(repoUrl);
-  } catch {
-    throw new Error('Invalid GitHub repository URL.');
-  }
-
-  const host = parsedUrl.hostname.replace(/^www\./, '').toLowerCase();
-  if (host !== 'github.com') {
-    throw new Error('Only GitHub repository URLs are supported.');
-  }
-
-  const parts = parsedUrl.pathname.split('/').filter(Boolean).map((part) => decodeURIComponent(part));
-  if (parts.length < 2) {
-    throw new Error('Expected a repository URL in the form https://github.com/owner/repo.');
-  }
-
-  const [owner, repoRaw] = parts;
-  return { owner, repo: repoRaw.replace(/\.git$/i, '') };
-}
-
-function encodePath(path) {
-  return String(path)
-    .split('/')
-    .map((segment) => encodeURIComponent(segment))
-    .join('/');
-}
-
-function decodeBase64(content) {
-  const normalized = String(content ?? '').replace(/\s+/g, '');
-
-  if (!normalized) {
-    return '';
-  }
-
-  if (typeof atob === 'function') {
-    return atob(normalized);
-  }
-
-  if (typeof Buffer !== 'undefined') {
-    return Buffer.from(normalized, 'base64').toString('utf8');
-  }
-
-  return '';
-}
-
-function responseMessage(response, payload) {
-  if (payload && typeof payload === 'object' && payload.message) {
-    return String(payload.message);
-  }
-
-  return `${response.status} ${response.statusText}`.trim();
-}
-
-function resolveGithubToken(options = {}) {
-  const explicitToken = cleanString(options.authToken ?? '');
-  if (explicitToken) {
-    return explicitToken;
-  }
-
-  const envToken = cleanString(import.meta.env?.VITE_GITHUB_TOKEN ?? '');
-  if (envToken) {
-    return envToken;
-  }
+  const trimmed = text.replace(/^git\+/, '').replace(/\.git$/i, '').replace(/\/+$/, '');
 
   try {
-    if (typeof window !== 'undefined' && window.localStorage) {
-      const localToken = cleanString(window.localStorage.getItem('opencite_github_token') ?? '');
-      if (localToken) {
-        return localToken;
-      }
+    const parsed = new URL(trimmed);
+    const host = parsed.hostname.toLowerCase();
+    let pathname = parsed.pathname.replace(/\/+$/, '');
+    if (host === 'github.com') {
+      pathname = pathname.toLowerCase();
     }
+    return `${parsed.protocol}//${host}${pathname}`;
   } catch {
-    // localStorage access can fail in restricted browsing contexts.
+    return trimmed;
   }
-
-  return '';
 }
 
-function createGithubHeaders(token = '') {
-  const headers = {
-    Accept: 'application/vnd.github+json',
-    'X-GitHub-Api-Version': '2022-11-28',
-  };
-
-  if (token) {
-    headers.Authorization = `Bearer ${token}`;
+function normalizeVersionForCompare(value) {
+  const text = cleanString(value).toLowerCase();
+  if (!text) {
+    return '';
   }
 
-  return headers;
+  // Treat v-prefixed tags and bare semver as equivalent for mismatch checks.
+  return text.replace(/^v(?=\d)/, '');
 }
 
 function addRateLimitHintIfNeeded(warnings, authToken) {
@@ -341,137 +282,169 @@ function addRateLimitHintIfNeeded(warnings, authToken) {
       warnings,
       'github-auth',
       'rate-limit-hint',
-      'To reduce rate limits, set VITE_GITHUB_TOKEN in your .env.local or set localStorage key opencite_github_token to a GitHub token with read access.',
+      'To reduce rate limits, pass authToken explicitly or set localStorage.opencite_github_token.',
     );
   }
 }
 
-async function fetchJson(url, authToken = '') {
-  let response;
+async function fetchOrcidFromGithubProfileHtml(profileUrl) {
+  const url = cleanString(profileUrl);
+  if (!url) {
+    return null;
+  }
 
   try {
-    response = await fetch(url, {
-      headers: createGithubHeaders(authToken),
+    const response = await fetch(url, {
+      headers: {
+        Accept: 'text/html',
+      },
     });
-  } catch (error) {
-    return {
-      ok: false,
-      status: 0,
-      statusText: 'Network error',
-      data: null,
-      rateLimited: false,
-      error: error instanceof Error ? error.message : String(error),
-    };
-  }
-
-  const text = await response.text();
-  let data = null;
 
-  if (text) {
-    try {
-      data = JSON.parse(text);
-    } catch {
-      data = text;
+    if (!response.ok) {
+      return null;
     }
-  }
 
-  return {
-    ok: response.ok,
-    status: response.status,
-    statusText: response.statusText,
-    data,
-    rateLimited: response.status === 403 && response.headers.get('x-ratelimit-remaining') === '0',
-  };
+    const html = await response.text();
+    return extractOrcidFromGithubHtml(html);
+  } catch {
+    return null;
+  }
 }
 
-async function fetchRequiredJson(url, errors, source, authToken = '') {
-  const result = await fetchJson(url, authToken);
+function shouldInspectRepositoryFiles(options = {}) {
+  return options.inspectRepositoryFiles !== false;
+}
 
-  if (!result.ok) {
-    const message = result.rateLimited
-      ? 'GitHub API rate limit exceeded.'
-      : responseMessage(result, result.data);
-    addError(errors, source, result.rateLimited ? 'rate-limited' : 'request-failed', message, { url });
-    return null;
+export function resolvePreferredCitationPath(fileContents = {}) {
+  if (fileContents['CITATION.cff']) {
+    return 'CITATION.cff';
   }
 
-  return result.data;
+  return '';
 }
 
-async function fetchOptionalJson(url, warnings, source, label, authToken = '') {
-  const result = await fetchJson(url, authToken);
+export function validateImportedMetadataFiles(fileContents = {}) {
+  return summarizeImportedMetadataFiles(fileContents).warnings;
+}
 
-  if (!result.ok) {
-    if (result.status === 404) {
-      return null;
+export function summarizeImportedMetadataFiles(fileContents = {}) {
+  const warnings = [];
+  const summary = {
+    citation: {
+      present: false,
+      valid: true,
+      path: '',
+      errors: [],
+    },
+    zenodo: {
+      present: false,
+      valid: true,
+      path: '.zenodo.json',
+      errors: [],
+    },
+    warnings,
+  };
+  const preferredCitationPath = resolvePreferredCitationPath(fileContents);
+
+  if (preferredCitationPath) {
+    const citationText = fileContents[preferredCitationPath];
+    summary.citation.present = true;
+    summary.citation.path = preferredCitationPath;
+
+    const citationValidation = validateCitationCffText(citationText);
+    if (!citationValidation.isValid) {
+      summary.citation.valid = false;
+      summary.citation.errors = [...citationValidation.errors];
+      addWarning(
+        warnings,
+        'citation',
+        'citation-file-invalid',
+        `${preferredCitationPath} failed validation: ${citationValidation.errors.join(' | ')}`,
+        { path: preferredCitationPath },
+      );
     }
 
-    const message = result.rateLimited
-      ? `GitHub API rate limit reached while fetching ${label}.`
-      : `${label} unavailable: ${responseMessage(result, result.data)}`;
-    addWarning(warnings, source, result.rateLimited ? 'rate-limited' : 'request-failed', message, { url });
-    return null;
+    for (const warning of citationValidation.warnings) {
+      addWarning(warnings, 'citation', 'citation-file-warning', `${preferredCitationPath}: ${warning}`, { path: preferredCitationPath });
+    }
   }
 
-  return result.data;
-}
-
-async function fetchContentsFile(owner, repo, path, ref, warnings, authToken = '') {
-  const url = `${API_BASE}/repos/${owner}/${repo}/contents/${encodePath(path)}?ref=${encodeURIComponent(ref)}`;
-  const result = await fetchJson(url, authToken);
-
-  if (!result.ok) {
-    if (result.status === 404) {
-      return null;
+  const zenodoPath = '.zenodo.json';
+  const zenodoText = fileContents[zenodoPath];
+  if (zenodoText) {
+    summary.zenodo.present = true;
+    const zenodoValidation = validateZenodoJsonText(zenodoText);
+    if (!zenodoValidation.isValid) {
+      summary.zenodo.valid = false;
+      summary.zenodo.errors = [...zenodoValidation.errors];
+      addWarning(
+        warnings,
+        'zenodo',
+        'zenodo-file-invalid',
+        `${zenodoPath} failed validation: ${zenodoValidation.errors.join(' | ')}`,
+        { path: zenodoPath },
+      );
     }
 
-    addWarning(
-      warnings,
-      'contents',
-      result.rateLimited ? 'rate-limited' : 'request-failed',
-      result.rateLimited
-        ? `GitHub API rate limit reached while fetching ${path}.`
-        : `Unable to fetch ${path}: ${responseMessage(result, result.data)}`,
-      { path, url },
-    );
-    return null;
+    for (const warning of zenodoValidation.warnings) {
+      addWarning(warnings, 'zenodo', 'zenodo-file-warning', `${zenodoPath}: ${warning}`, { path: zenodoPath });
+    }
   }
 
-  const payload = result.data;
-  if (!payload || Array.isArray(payload)) {
-    addWarning(warnings, 'contents', 'unexpected-response', `GitHub returned an unexpected payload for ${path}.`, { path, url });
-    return null;
-  }
+  return summary;
+}
 
-  if (payload.truncated && payload.download_url) {
-    const rawResult = await fetchJson(payload.download_url, authToken);
-    if (rawResult.ok) {
-      return typeof rawResult.data === 'string' ? rawResult.data : '';
-    }
+function resolveContributorFallbackLimit(options = {}) {
+  if (!Object.prototype.hasOwnProperty.call(options, 'contributorFallbackLimit')) {
+    return TOP_CONTRIBUTOR_FALLBACK_LIMIT;
+  }
 
-    addWarning(warnings, 'contents', 'request-failed', `Unable to fetch the full contents of ${path}.`, { path, url });
+  if (options.contributorFallbackLimit == null || options.contributorFallbackLimit === '') {
     return null;
   }
 
-  if (payload.encoding === 'base64' && payload.content) {
-    return decodeBase64(payload.content);
+  const rawLimit = Number(options.contributorFallbackLimit);
+
+  if (!Number.isFinite(rawLimit)) {
+    return TOP_CONTRIBUTOR_FALLBACK_LIMIT;
   }
 
-  return '';
+  return Math.min(Math.max(Math.trunc(rawLimit), 1), MAX_CONTRIBUTOR_FALLBACK_LIMIT);
 }
 
-function shouldInspectRepositoryFiles(options = {}) {
-  return options.inspectRepositoryFiles === true;
-}
+async function fetchAllContributors(owner, repo, warnings, authToken = '', maxContributors = null) {
+  const contributors = [];
+  let page = 1;
 
-function resolveContributorFallbackLimit(options = {}) {
-  const rawLimit = Number(options.contributorFallbackLimit);
+  while (true) {
+    const pageContributors = await fetchOptionalJson(
+      `${API_BASE}/repos/${owner}/${repo}/contributors?per_page=${GITHUB_PAGE_SIZE}&page=${page}`,
+      {
+        authToken,
+        source: 'contributors',
+        label: `contributors page ${page}`,
+        onWarning: (source, code, message, details = {}) => addWarning(warnings, source, code, message, details),
+      },
+    ) || [];
+
+    if (!Array.isArray(pageContributors) || pageContributors.length === 0) {
+      break;
+    }
 
-  if (!Number.isFinite(rawLimit)) {
-    return TOP_CONTRIBUTOR_FALLBACK_LIMIT;
+    contributors.push(...pageContributors);
+
+    if (maxContributors && contributors.length >= maxContributors) {
+      return contributors.slice(0, maxContributors);
+    }
+
+    if (pageContributors.length < GITHUB_PAGE_SIZE) {
+      break;
+    }
+
+    page += 1;
   }
 
-  return Math.min(Math.max(Math.trunc(rawLimit), 1), MAX_CONTRIBUTOR_FALLBACK_LIMIT);
+  return contributors;
 }
 
 function extractFirstMarkdownParagraph(text) {
@@ -505,7 +478,7 @@ function extractFirstMarkdownParagraph(text) {
   return paragraph.join(' ').replace(/\s+/g, ' ').trim();
 }
 
-function parseCitationCff(text) {
+export function parseCitationCff(text) {
   const lines = String(text ?? '').replace(/\r\n/g, '\n').split('\n');
   const result = {
     title: '',
@@ -519,18 +492,58 @@ function parseCitationCff(text) {
     authors: [],
     references: [],
   };
+  const parseWarnings = [];
 
   let section = 'top';
   let currentAuthor = null;
+  let currentReference = null;
 
   const flushAuthor = () => {
-    if (currentAuthor && (currentAuthor.givenNames || currentAuthor.familyNames || currentAuthor.orcid || currentAuthor.affiliation)) {
+    const hasAuthorData = currentAuthor && (
+      currentAuthor.givenNames
+      || currentAuthor.familyNames
+      || currentAuthor['given-names']
+      || currentAuthor['family-names']
+      || currentAuthor.orcid
+      || currentAuthor.affiliation
+    );
+
+    if (hasAuthorData) {
       result.authors.push(currentAuthor);
     }
 
     currentAuthor = null;
   };
 
+  const flushReference = () => {
+    if (!currentReference || typeof currentReference !== 'object') {
+      currentReference = null;
+      return;
+    }
+
+    const doi = cleanString(currentReference.doi ?? currentReference.DOI ?? '');
+    const url = cleanString(currentReference.url ?? currentReference.link ?? currentReference.value ?? '');
+    const title = cleanString(currentReference.title ?? currentReference['article-title'] ?? currentReference.reference ?? currentReference.text ?? '');
+
+    if (doi) {
+      result.references.push(/^https?:\/\//i.test(doi) ? doi : `https://doi.org/${doi}`);
+      currentReference = null;
+      return;
+    }
+
+    if (url) {
+      result.references.push(url);
+      currentReference = null;
+      return;
+    }
+
+    if (title) {
+      result.references.push(title);
+    }
+
+    currentReference = null;
+  };
+
   const assignScalar = (key, value) => {
     const normalized = cleanString(value).replace(/^"|"$/g, '');
 
@@ -587,7 +600,7 @@ function parseCitationCff(text) {
       continue;
     }
 
-    if (section === 'keywords' || section === 'references') {
+    if (section === 'keywords') {
       if (indent === 0 && !trimmed.startsWith('-')) {
         section = 'top';
         index -= 1;
@@ -596,10 +609,48 @@ function parseCitationCff(text) {
 
       if (trimmed.startsWith('-')) {
         const value = cleanString(trimmed.slice(1)).replace(/^"|"$/g, '');
-        if (section === 'keywords') {
-          result.keywords.push(value);
+        result.keywords.push(value);
+      }
+
+      continue;
+    }
+
+    if (section === 'references') {
+      if (indent === 0 && !trimmed.startsWith('-')) {
+        flushReference();
+        section = 'top';
+        index -= 1;
+        continue;
+      }
+
+      if (trimmed.startsWith('-')) {
+        flushReference();
+
+        const inline = cleanString(trimmed.slice(1)).replace(/^"|"$/g, '');
+        if (!inline) {
+          currentReference = {};
+          continue;
+        }
+
+        const inlineMatch = inline.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
+        if (inlineMatch) {
+          const [, key, value] = inlineMatch;
+          currentReference = {
+            [key]: cleanString(value).replace(/^"|"$/g, ''),
+          };
         } else {
-          result.references.push(value);
+          result.references.push(inline);
+          currentReference = null;
+        }
+
+        continue;
+      }
+
+      if (currentReference) {
+        const referenceMatch = trimmed.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
+        if (referenceMatch) {
+          const [, key, value] = referenceMatch;
+          currentReference[key] = cleanString(value).replace(/^"|"$/g, '');
         }
       }
 
@@ -647,6 +698,11 @@ function parseCitationCff(text) {
       continue;
     }
 
+    if (/^preferred-citation:\s*$/i.test(trimmed)) {
+      parseWarnings.push('preferred-citation section is not fully parsed during import; using top-level citation fields.');
+      continue;
+    }
+
     const scalarMatch = trimmed.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
     if (scalarMatch) {
       assignScalar(scalarMatch[1], scalarMatch[2]);
@@ -654,12 +710,14 @@ function parseCitationCff(text) {
   }
 
   flushAuthor();
+  flushReference();
 
   return {
     ...result,
     keywords: normalizeKeywords(result.keywords),
     authors: normalizeAuthors(result.authors),
     references: normalizeReferences(result.references),
+    _warnings: parseWarnings,
   };
 }
 
@@ -667,7 +725,7 @@ function parseJsonSafely(text) {
   return JSON.parse(text);
 }
 
-function parseZenodoJson(text) {
+export function parseZenodoJson(text) {
   const payload = parseJsonSafely(text);
 
   const creators = Array.isArray(payload.creators) ? payload.creators.map((creator) => normalizeAuthor(creator)).filter(Boolean) : [];
@@ -864,8 +922,15 @@ function parseFile(path, text, warnings, errors) {
       return parseZenodoJson(text);
     }
 
-    if (path === 'CITATION.cff' || path === 'citation.cff') {
-      return parseCitationCff(text);
+    if (path === 'CITATION.cff') {
+      const parsed = parseCitationCff(text);
+      if (Array.isArray(parsed._warnings)) {
+        for (const warning of parsed._warnings) {
+          addWarning(warnings, 'parser', 'citation-partial-parse', warning, { path });
+        }
+      }
+      const { _warnings, ...safeParsed } = parsed;
+      return safeParsed;
     }
 
     if (path === 'package.json') {
@@ -892,7 +957,7 @@ function parseFile(path, text, warnings, errors) {
       return { abstract: parseReadme(text) };
     }
   } catch (error) {
-    addWarning(warnings, 'parser', 'parse-failed', `Could not parse ${path}: ${error instanceof Error ? error.message : String(error)}`, { path });
+    addWarning(warnings, 'parser', 'parse-failed', `Could not parse ${path}. ${error instanceof Error ? error.message : String(error)}`, { path });
     return null;
   }
 
@@ -918,23 +983,164 @@ function mapTypeOfWork(value) {
   return 'software';
 }
 
-function mergeMetadata({ repo, release, citation, zenodo, packageMeta, readme, contributors }) {
-  const authors = firstNonEmpty(citation?.authors, zenodo?.authors, packageMeta?.authors, contributors);
+function authorNameKey(author) {
+  return [
+    cleanString(author?.givenNames ?? '').toLowerCase(),
+    cleanString(author?.familyNames ?? '').toLowerCase(),
+  ].join('|');
+}
+
+function normalizeNameToken(value) {
+  return cleanString(value)
+    .toLowerCase()
+    .replace(/[^a-z0-9\s]/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+function authorMatchMetadata(author) {
+  const givenNames = normalizeNameToken(author?.givenNames ?? '');
+  const familyNames = normalizeNameToken(author?.familyNames ?? '');
+  const givenTokens = givenNames.split(' ').filter(Boolean);
+  const familyTokens = familyNames.split(' ').filter(Boolean);
+
+  return {
+    givenNames,
+    familyNames,
+    givenFirst: givenTokens[0] ?? '',
+    givenInitials: givenTokens.map((token) => token[0]).join(''),
+    familyLast: familyTokens[familyTokens.length - 1] ?? '',
+    fullName: [givenNames, familyNames].filter(Boolean).join(' ').trim(),
+  };
+}
+
+function authorAltNameKeys(author) {
+  const metadata = authorMatchMetadata(author);
+  const givenNames = metadata.givenNames;
+  const familyNames = metadata.familyNames;
+  const givenFirst = metadata.givenFirst;
+  const familyLast = metadata.familyLast;
+  const keys = new Set([
+    `${givenNames}|${familyNames}`,
+    `${givenFirst}|${familyNames}`,
+    `${givenNames}|${familyLast}`,
+    `${givenFirst}|${familyLast}`,
+  ]);
+
+  keys.delete('|');
+  keys.delete('');
+  return [...keys].filter(Boolean);
+}
+
+function authorsLikelyMatch(sourceAuthor, contributorAuthor) {
+  const source = authorMatchMetadata(sourceAuthor);
+  const contributor = authorMatchMetadata(contributorAuthor);
+
+  if (!source.familyLast || !contributor.familyLast || source.familyLast !== contributor.familyLast) {
+    return false;
+  }
+
+  if (source.givenNames && contributor.givenNames && source.givenNames === contributor.givenNames) {
+    return true;
+  }
+
+  if (source.givenFirst && contributor.givenFirst && source.givenFirst === contributor.givenFirst) {
+    return true;
+  }
+
+  if (source.givenInitials && contributor.givenInitials && source.givenInitials === contributor.givenInitials) {
+    return true;
+  }
+
+  if (source.fullName && contributor.fullName && source.fullName === contributor.fullName) {
+    return true;
+  }
+
+  return false;
+}
+
+function enrichAuthorsWithContributorData(sourceAuthors, contributorAuthors) {
+  const normalizedSourceAuthors = normalizeAuthors(Array.isArray(sourceAuthors) ? sourceAuthors : []);
+  if (normalizedSourceAuthors.length === 0) {
+    return normalizeAuthors(Array.isArray(contributorAuthors) ? contributorAuthors : []);
+  }
+
+  const normalizedContributorAuthors = normalizeAuthors(Array.isArray(contributorAuthors) ? contributorAuthors : []);
+  const contributorMatches = new Map();
+
+  for (const contributorAuthor of normalizedContributorAuthors) {
+    if (!contributorAuthor.orcid && !contributorAuthor.affiliation) {
+      continue;
+    }
+
+    for (const key of authorAltNameKeys(contributorAuthor)) {
+      const existing = contributorMatches.get(key) ?? [];
+      existing.push(contributorAuthor);
+      contributorMatches.set(key, existing);
+    }
+  }
+
+  return normalizedSourceAuthors.map((author) => {
+    const keyedMatches = authorAltNameKeys(author)
+      .flatMap((key) => contributorMatches.get(key) ?? []);
+    const heuristicMatches = normalizedContributorAuthors.filter((contributorAuthor) => authorsLikelyMatch(author, contributorAuthor));
+    const matches = [...new Set([...keyedMatches, ...heuristicMatches])];
+    const uniqueOrcids = [...new Set(matches.map((match) => match.orcid).filter(Boolean))];
+    const uniqueAffiliations = [...new Set(matches.map((match) => match.affiliation).filter(Boolean))];
+
+    if ((!author.orcid && uniqueOrcids.length > 1) || (!author.affiliation && uniqueAffiliations.length > 1)) {
+      return author;
+    }
+
+    return {
+      ...author,
+      orcid: author.orcid || uniqueOrcids[0] || '',
+      affiliation: author.affiliation || uniqueAffiliations[0] || '',
+    };
+  });
+}
+
+function mergeMetadata({
+  repo,
+  release,
+  defaultPublicationDate,
+  citation,
+  zenodo,
+  packageMeta,
+  readme,
+  contributors,
+  contributorLookupAuthors,
+  supplementalCitationAuthors = [],
+}) {
+  const primaryAuthors = [
+    ...normalizeAuthors(Array.isArray(citation?.authors) ? citation.authors : []),
+    ...normalizeAuthors(Array.isArray(zenodo?.authors) ? zenodo.authors : []),
+    ...normalizeAuthors(Array.isArray(packageMeta?.authors) ? packageMeta.authors : []),
+    ...normalizeAuthors(Array.isArray(supplementalCitationAuthors) ? supplementalCitationAuthors : []),
+  ];
+  const authors = [
+    ...normalizeAuthors(primaryAuthors),
+    ...normalizeAuthors(Array.isArray(contributors) ? contributors : []),
+  ];
   const keywords = normalizeKeywords(firstNonEmpty(citation?.keywords, zenodo?.keywords, packageMeta?.keywords, repo?.topics));
   const references = normalizeReferences(firstNonEmpty(zenodo?.references, citation?.references));
   const grants = normalizeGrants(firstNonEmpty(zenodo?.grants));
+  const enrichedAuthors = enrichAuthorsWithContributorData(authors, contributorLookupAuthors);
+  const dedupedAuthors = dedupeAuthors(enrichedAuthors);
+  const orderedAuthors = orderAuthorsByContributorRank(dedupedAuthors, contributorLookupAuthors);
 
   return createMetadata({
     title: cleanString(firstNonEmpty(citation?.title, zenodo?.title, packageMeta?.title, repo?.name)),
-    authors: normalizeAuthors(authors),
+    authors: orderedAuthors,
     keywords,
     license: cleanString(firstNonEmpty(citation?.license, zenodo?.license, packageMeta?.license, repo?.license?.spdx_id)),
     typeOfWork: mapTypeOfWork(firstNonEmpty(zenodo?.typeOfWork, citation?.typeOfWork, 'software')),
     customTypeOfWork: '',
     zenodoUploadType: mapTypeOfWork(firstNonEmpty(zenodo?.typeOfWork, citation?.typeOfWork, 'software')),
-    version: cleanString(firstNonEmpty(citation?.version, zenodo?.version, release?.tag_name, packageMeta?.version)),
-    publicationDate: cleanString(firstNonEmpty(citation?.publicationDate, zenodo?.publicationDate, release?.published_at, repo?.created_at)).split('T')[0],
-    repositoryCode: cleanString(firstNonEmpty(citation?.repositoryCode, packageMeta?.repositoryCode, repo?.html_url)),
+    // Prefer metadata file versions for pre-release authoring; fall back to latest release tag.
+    version: cleanString(firstNonEmpty(citation?.version, zenodo?.version, packageMeta?.version, release?.tag_name)),
+    publicationDate: cleanString(firstNonEmpty(release?.published_at, citation?.publicationDate, zenodo?.publicationDate, defaultPublicationDate)).split('T')[0],
+    repositoryCode: normalizeRepoUrl(firstNonEmpty(repo?.html_url, citation?.repositoryCode, packageMeta?.repositoryCode)),
     doi: cleanString(firstNonEmpty(zenodo?.doi, citation?.doi)),
     abstract: cleanString(firstNonEmpty(citation?.abstract, zenodo?.abstract, packageMeta?.abstract, readme, repo?.description)),
     references,
@@ -942,6 +1148,108 @@ function mergeMetadata({ repo, release, citation, zenodo, packageMeta, readme, c
   });
 }
 
+export function addCitationConsistencyWarnings({ warnings, citation, zenodo, releaseData, repoData, metadata }) {
+  const releaseTag = cleanString(releaseData?.tag_name ?? '');
+  const citationVersion = cleanString(citation?.version ?? '');
+  const zenodoVersion = cleanString(zenodo?.version ?? '');
+  const finalVersion = cleanString(metadata?.version ?? '');
+  const normalizedReleaseTag = normalizeVersionForCompare(releaseTag);
+  const normalizedCitationVersion = normalizeVersionForCompare(citationVersion);
+  const normalizedZenodoVersion = normalizeVersionForCompare(zenodoVersion);
+
+  if (normalizedReleaseTag && normalizedCitationVersion && normalizedReleaseTag !== normalizedCitationVersion) {
+    addWarning(
+      warnings,
+      'citation',
+      'version-mismatch',
+      `CITATION.cff version (${citationVersion}) differs from latest release tag (${releaseTag}); using CITATION.cff version for import.`,
+    );
+  }
+
+  if (normalizedReleaseTag && normalizedZenodoVersion && normalizedReleaseTag !== normalizedZenodoVersion) {
+    addWarning(
+      warnings,
+      'zenodo',
+      'version-mismatch',
+      `.zenodo.json version (${zenodoVersion}) differs from latest release tag (${releaseTag}); using .zenodo.json version for import.`,
+    );
+  }
+
+  if (normalizedCitationVersion && normalizedZenodoVersion && normalizedCitationVersion !== normalizedZenodoVersion) {
+    addWarning(
+      warnings,
+      'citation',
+      'cross-file-version-mismatch',
+      `CITATION.cff version (${citationVersion}) and .zenodo.json version (${zenodoVersion}) differ.`,
+    );
+  }
+
+  const citationDate = cleanString(citation?.publicationDate ?? '').split('T')[0];
+  const zenodoDate = cleanString(zenodo?.publicationDate ?? '').split('T')[0];
+  const releaseDate = cleanString(releaseData?.published_at ?? '').split('T')[0];
+
+  if (releaseDate && citationDate && releaseDate !== citationDate) {
+    addWarning(
+      warnings,
+      'citation',
+      'date-mismatch',
+      `CITATION.cff date-released (${citationDate}) differs from latest release date (${releaseDate}); using release date for import.`,
+    );
+  }
+
+  if (releaseDate && zenodoDate && releaseDate !== zenodoDate) {
+    addWarning(
+      warnings,
+      'zenodo',
+      'date-mismatch',
+      `.zenodo.json publication_date (${zenodoDate}) differs from latest release date (${releaseDate}); using release date for import.`,
+    );
+  }
+
+  const repoUrl = normalizeRepoUrl(repoData?.html_url ?? '');
+  const citationRepoUrl = normalizeRepoUrl(citation?.repositoryCode ?? '');
+
+  if (repoUrl && citationRepoUrl && repoUrl !== citationRepoUrl) {
+    addWarning(
+      warnings,
+      'citation',
+      'repository-url-mismatch',
+      `CITATION.cff repository-code (${citationRepoUrl}) differs from repository URL (${repoUrl}); using repository URL for import.`,
+    );
+  }
+
+  if (!finalVersion) {
+    addWarning(
+      warnings,
+      'citation',
+      'missing-version',
+      'No version could be determined from release tag, CITATION.cff, .zenodo.json, or package metadata.',
+    );
+  }
+
+  const repoSpdx = cleanString(repoData?.license?.spdx_id ?? '').toUpperCase();
+  const citationLicense = cleanString(citation?.license ?? '').toUpperCase();
+  const zenodoLicense = cleanString(zenodo?.license ?? '').toUpperCase();
+
+  if (repoSpdx && citationLicense && repoSpdx !== citationLicense) {
+    addWarning(
+      warnings,
+      'citation',
+      'license-mismatch',
+      `CITATION.cff license (${citationLicense}) differs from repository SPDX license (${repoSpdx}); imported metadata keeps source precedence but should be reviewed.`,
+    );
+  }
+
+  if (repoSpdx && zenodoLicense && repoSpdx !== zenodoLicense) {
+    addWarning(
+      warnings,
+      'zenodo',
+      'license-mismatch',
+      `.zenodo.json license (${zenodoLicense}) differs from repository SPDX license (${repoSpdx}); imported metadata keeps source precedence but should be reviewed.`,
+    );
+  }
+}
+
 export async function importGithubMetadata(repoUrl, options = {}) {
   const warnings = [];
   const errors = [];
@@ -957,80 +1265,157 @@ export async function importGithubMetadata(repoUrl, options = {}) {
     ({ owner, repo } = parseGithubUrl(repoUrl));
   } catch (error) {
     addError(errors, 'url', 'invalid-url', error instanceof Error ? error.message : String(error));
-    return { metadata: emptyMetadata, warnings, errors };
+    return { metadata: emptyMetadata, warnings, errors, review: null, healthScan: [] };
   }
 
-  const repoData = await fetchRequiredJson(`${API_BASE}/repos/${owner}/${repo}`, errors, 'repository', authToken);
+  const repoData = await fetchRequiredJson(`${API_BASE}/repos/${owner}/${repo}`, {
+    authToken,
+    source: 'repository',
+    onError: (source, code, message, details = {}) => addError(errors, source, code, message, details),
+  });
   if (!repoData) {
-    return { metadata: emptyMetadata, warnings, errors };
+    return { metadata: emptyMetadata, warnings, errors, review: null, healthScan: [] };
   }
 
   const defaultBranch = cleanString(repoData.default_branch ?? '');
-  const releaseData = await fetchOptionalJson(
-    `${API_BASE}/repos/${owner}/${repo}/releases/latest`,
-    warnings,
-    'release',
-    'the latest release',
+  const releaseData = await fetchOptionalJson(`${API_BASE}/repos/${owner}/${repo}/releases/latest`, {
     authToken,
-  );
+    source: 'release',
+    label: 'the latest release',
+    onWarning: (source, code, message, details = {}) => addWarning(warnings, source, code, message, details),
+  });
+  const latestCommitDate = releaseData?.published_at
+    ? ''
+    : await fetchLatestCommitDate(owner, repo, defaultBranch, {
+        authToken,
+        onWarning: (source, code, message, details = {}) => addWarning(warnings, source, code, message, details),
+      });
 
   const parsedFiles = {};
+  const fileContents = {};
+
+  let ref = 'HEAD';
+
   if (inspectRepositoryFiles) {
     const branchInfo = defaultBranch
-      ? await fetchOptionalJson(
-          `${API_BASE}/repos/${owner}/${repo}/branches/${encodeURIComponent(defaultBranch)}`,
-          warnings,
-          'branch',
-          'the default branch',
+      ? await fetchOptionalJson(`${API_BASE}/repos/${owner}/${repo}/branches/${encodeURIComponent(defaultBranch)}`, {
           authToken,
-        )
+          source: 'branch',
+          label: 'the default branch',
+          onWarning: (source, code, message, details = {}) => addWarning(warnings, source, code, message, details),
+        })
       : null;
 
-    const ref = cleanString(branchInfo?.name ?? defaultBranch ?? repoData.default_branch ?? 'HEAD');
+    ref = cleanString(branchInfo?.name ?? defaultBranch ?? repoData.default_branch ?? 'HEAD');
+
     const fileEntries = await Promise.all(
-      FILES_TO_INSPECT.map(async (filePath) => [filePath, await fetchContentsFile(owner, repo, filePath, ref, warnings, authToken)]),
+      FILES_TO_INSPECT.map(async (filePath) => [
+        filePath,
+        await fetchContentsFile(owner, repo, filePath, ref, {
+          authToken,
+          onWarning: (source, code, message, details = {}) => addWarning(warnings, source, code, message, details),
+        }),
+      ]),
     );
 
-    const fileContents = Object.fromEntries(fileEntries);
+    Object.assign(fileContents, Object.fromEntries(fileEntries));
+    const preferredCitationPath = resolvePreferredCitationPath(fileContents);
 
     for (const filePath of FILES_TO_INSPECT) {
-      const text = fileContents[filePath];
-      if (!text) {
+      if (
+        filePath === 'CITATION.cff'
+        && preferredCitationPath
+        && filePath !== preferredCitationPath
+      ) {
         continue;
       }
 
+      const text = fileContents[filePath];
+      if (!text) continue;
+
       const parsed = parseFile(filePath, text, warnings, errors);
       if (parsed) {
-        parsedFiles[filePath.toLowerCase()] = parsed;
+        const parsedKey = (filePath === 'CITATION.cff')
+          ? 'CITATION.cff'
+          : filePath.toLowerCase();
+        parsedFiles[parsedKey] = parsed;
       }
     }
   }
 
-  const citation = parsedFiles['citation.cff'];
-  const zenodo = parsedFiles['.zenodo.json'];
+  const fileValidationSummary = summarizeImportedMetadataFiles(fileContents);
+
+  for (const validationWarning of fileValidationSummary.warnings) {
+    warnings.push(validationWarning);
+  }
+
+  const citationForComparison = parsedFiles['CITATION.cff'] ?? null;
+  const zenodoForComparison = parsedFiles['.zenodo.json'] ?? null;
+
+  let citation = citationForComparison;
+  let zenodo = zenodoForComparison;
+  let supplementalCitationAuthors = [];
+
+  if (fileValidationSummary.citation.present && !fileValidationSummary.citation.valid) {
+    // Discard invalid citation metadata fields, but keep parsed authors for attribution.
+    supplementalCitationAuthors = normalizeAuthors(citationForComparison?.authors ?? []);
+    citation = null;
+    addWarning(
+      warnings,
+      'citation',
+      'citation-file-skipped',
+      `${fileValidationSummary.citation.path || 'CITATION.cff'} is invalid; ignoring non-author citation fields to avoid propagating incorrect values, but preserving parsed author entries and continuing with repository/package/README/contributor fallback metadata.`,
+      { path: fileValidationSummary.citation.path || 'CITATION.cff' },
+    );
+  }
+
+  if (fileValidationSummary.zenodo.present && !fileValidationSummary.zenodo.valid) {
+    zenodo = null;
+    addWarning(
+      warnings,
+      'zenodo',
+      'zenodo-file-skipped',
+      '.zenodo.json is invalid; ignoring imported Zenodo metadata to avoid propagating incorrect values and continuing with repository/package/README/contributor fallback metadata.',
+      { path: '.zenodo.json' },
+    );
+  }
+
   const packageMeta = parsedFiles['package.json'] || parsedFiles['pyproject.toml'] || parsedFiles['setup.py'] || parsedFiles['cargo.toml'] || parsedFiles['pom.xml'];
   const readme = parsedFiles['readme.md']?.abstract || '';
+  const hasPrimaryAuthors = firstNonEmpty(citation?.authors, zenodo?.authors, packageMeta?.authors, supplementalCitationAuthors).length > 0;
 
-  const contributors = (await fetchContributorAuthors(owner, repo, warnings, authToken, contributorFallbackLimit)).filter(Boolean);
+  const contributorResult = await fetchContributorAuthors(
+    owner,
+    repo,
+    warnings,
+    authToken,
+    contributorFallbackLimit,
+    !hasPrimaryAuthors,
+  );
+  const contributors = contributorResult.fallbackAuthors.filter(Boolean);
+  const contributorLookupAuthors = contributorResult.lookupAuthors.filter(Boolean);
 
   addRateLimitHintIfNeeded(warnings, authToken);
 
   if (!firstNonEmpty(citation?.authors, zenodo?.authors, packageMeta?.authors, contributors).length) {
-    addWarning(warnings, 'authors', 'missing-authors', 'No human-readable author names were found in the repository metadata.', { owner, repo });
+    addWarning(warnings, 'authors', 'missing-authors', 'No author names found in repository metadata.', { owner, repo });
   }
 
   const metadata = mergeMetadata({
     repo: repoData,
     release: releaseData,
+    defaultPublicationDate: latestCommitDate,
     citation,
     zenodo,
     packageMeta,
     readme,
     contributors,
+    contributorLookupAuthors,
+    supplementalCitationAuthors,
   });
 
   if (!metadata.repositoryCode) {
-    metadata.repositoryCode = cleanString(repoData.html_url ?? `https://github.com/${owner}/${repo}`);
+    metadata.repositoryCode = normalizeRepoUrl(repoData.html_url ?? `https://github.com/${owner}/${repo}`);
   }
 
   if (!metadata.version && releaseData?.tag_name) {
@@ -1038,60 +1423,144 @@ export async function importGithubMetadata(repoUrl, options = {}) {
   }
 
   if (!metadata.publicationDate) {
-    metadata.publicationDate = cleanString(releaseData?.published_at ?? repoData.created_at).split('T')[0];
+    metadata.publicationDate = cleanString(releaseData?.published_at ?? latestCommitDate ?? repoData.created_at).split('T')[0];
   }
 
-  return { metadata, warnings, errors };
-}
+  addCitationConsistencyWarnings({
+    warnings,
+    citation,
+    zenodo,
+    releaseData,
+    repoData,
+    metadata,
+  });
 
-async function fetchContributorAuthors(owner, repo, warnings, authToken = '', contributorFallbackLimit = TOP_CONTRIBUTOR_FALLBACK_LIMIT) {
-  const contributors = await fetchOptionalJson(
-    `${API_BASE}/repos/${owner}/${repo}/contributors?per_page=${contributorFallbackLimit}`,
+  const review = runMetadataReviewPipeline({
     warnings,
-    'contributors',
-    'contributors',
-    authToken,
-  ) || [];
+    errors,
+    metadata,
+    repoData,
+    releaseData,
+    fileValidationSummary,
+    citation,
+    zenodo,
+    packageMeta,
+  });
+
+  const healthScan = runCitationHealthScan({
+    warnings,
+    errors,
+    metadata,
+    repoData,
+    releaseData,
+    fileValidationSummary,
+    citation,
+    zenodo,
+    packageMeta,
+  });
+
+  const comparisons = compareExistingMetadataFiles({
+    repoData,
+    releaseData,
+    fileValidationSummary,
+    citationForComparison,
+    zenodoForComparison,
+    contributorLookupAuthors,
+  });
+
+  return { metadata, warnings, errors, review, healthScan, comparisons };
+}
+
+async function fetchContributorAuthors(
+  owner,
+  repo,
+  warnings,
+  authToken = '',
+  contributorFallbackLimit = TOP_CONTRIBUTOR_FALLBACK_LIMIT,
+  emitFallbackWarning = true,
+) {
+  const contributors = await fetchAllContributors(owner, repo, warnings, authToken, contributorFallbackLimit);
 
   if (!Array.isArray(contributors) || contributors.length === 0) {
-    return [];
+    return {
+      fallbackAuthors: [],
+      lookupAuthors: [],
+    };
   }
 
-  addWarning(
-    warnings,
-    'authors',
-    'commit-based-fallback',
-    `Using top ${contributorFallbackLimit} contributors by commit activity as author fallback.`,
-    { owner, repo },
-  );
+  if (emitFallbackWarning) {
+    addWarning(
+      warnings,
+      'authors',
+      'commit-based-fallback',
+      contributorFallbackLimit
+        ? `Using top ${contributorFallbackLimit} contributors as fallback authors.`
+        : 'Using contributors as fallback authors.',
+      { owner, repo },
+    );
+  }
 
   const profiles = await Promise.all(
-    contributors.slice(0, contributorFallbackLimit).map(async (contributor) => {
+    contributors.map(async (contributor) => {
       const login = cleanString(contributor?.login ?? '');
       if (!login) {
-        return { contributor, profile: null, author: null, excludedAutomated: false };
+        return {
+          contributor,
+          profile: null,
+          socialAccounts: [],
+          author: null,
+          autoFilledOrcid: false,
+          excludedAutomated: false,
+        };
       }
 
       const profile = await fetchOptionalJson(
         `${API_BASE}/users/${encodeURIComponent(login)}`,
-        warnings,
-        'contributor-profile',
-        `the profile for ${login}`,
-        authToken,
+        {
+          authToken,
+          source: 'contributor-profile',
+          label: `the profile for ${login}`,
+          onWarning: (source, code, message, details = {}) => addWarning(warnings, source, code, message, details),
+        },
       );
 
+      const socialAccounts = await fetchOptionalJson(
+        `${API_BASE}/users/${encodeURIComponent(login)}/social_accounts`,
+        {
+          authToken,
+          source: 'contributor-profile-links',
+          label: `the profile links for ${login}`,
+          onWarning: (source, code, message, details = {}) => addWarning(warnings, source, code, message, details),
+        },
+      ) || [];
+
       if (isAutomatedContributor(contributor, profile)) {
-        return { contributor, profile, author: null, excludedAutomated: true };
+        return {
+          contributor,
+          profile,
+          socialAccounts,
+          author: null,
+          autoFilledOrcid: false,
+          excludedAutomated: true,
+        };
+      }
+
+      let profileOrcid = extractOrcidFromGithubProfile(profile, socialAccounts);
+      if (!profileOrcid) {
+        profileOrcid = await fetchOrcidFromGithubProfileHtml(profile?.html_url ?? contributor?.html_url ?? '');
       }
 
       if (profile?.name) {
         return {
           contributor,
           profile,
+          socialAccounts,
           author: normalizeAuthor({
             name: profile.name,
             affiliation: profile.company ?? '',
+            orcid: profileOrcid,
           }),
+          autoFilledOrcid: Boolean(profileOrcid),
           excludedAutomated: false,
         };
       }
@@ -1100,10 +1569,13 @@ async function fetchContributorAuthors(owner, repo, warnings, authToken = '', co
       return {
         contributor,
         profile,
+        socialAccounts,
         author: normalizeAuthor({
           name: login,
           affiliation: '',
+          orcid: profileOrcid,
         }),
+        autoFilledOrcid: Boolean(profileOrcid),
         excludedAutomated: false,
       };
     }),
@@ -1115,19 +1587,104 @@ async function fetchContributorAuthors(owner, repo, warnings, authToken = '', co
       warnings,
       'authors',
       'automated-contributors-excluded',
-      `Excluded ${excludedAutomatedCount} automated contributor account(s) from author fallback.`,
+      `Excluded ${excludedAutomatedCount} automated account(s) from fallback authors.`,
       { owner, repo },
     );
   }
 
-  return dedupeAuthors(profiles.map((entry) => entry?.author).filter(Boolean));
+  const autoFilledOrcidCount = profiles.filter((entry) => entry?.autoFilledOrcid).length;
+  if (autoFilledOrcidCount > 0) {
+    addWarning(
+      warnings,
+      'authors',
+      'orcid-autofilled',
+      `Auto-filled ORCID for ${autoFilledOrcidCount} contributor(s) from GitHub profile data.`,
+      { owner, repo },
+    );
+  }
+
+  const fallbackAuthors = profiles
+    .slice(0, contributorFallbackLimit ?? profiles.length)
+    .map((entry) => entry?.author);
+  const lookupAuthors = profiles.map((entry) => entry?.author);
+
+  return {
+    fallbackAuthors: dedupeAuthors(normalizeAuthors(fallbackAuthors)),
+    lookupAuthors: dedupeAuthors(normalizeAuthors(lookupAuthors)),
+  };
 }
 
 function dedupeAuthors(authors) {
   const seen = new Set();
+  const byOrcid = new Map();
+  const byName = new Map();
   const deduped = [];
 
-  for (const author of authors) {
+  for (const rawAuthor of authors) {
+    const author = normalizeAuthor(rawAuthor);
+    if (!author) {
+      continue;
+    }
+
+    const orcidKey = cleanString(author?.orcid ?? '').toLowerCase();
+    const nameKey = [
+      cleanString(author?.givenNames ?? '').toLowerCase(),
+      cleanString(author?.familyNames ?? '').toLowerCase(),
+    ].join('|');
+
+    if (nameKey !== '|' && byName.has(nameKey)) {
+      const existing = byName.get(nameKey);
+      const existingOrcid = cleanString(existing?.orcid ?? '').toLowerCase();
+      const canMergeByName = !existingOrcid || !orcidKey || existingOrcid === orcidKey;
+
+      if (canMergeByName) {
+        if (!existing.orcid && author.orcid) {
+          existing.orcid = author.orcid;
+        }
+        if (!existing.affiliation && author.affiliation) {
+          existing.affiliation = author.affiliation;
+        }
+        if (orcidKey && !byOrcid.has(orcidKey)) {
+          byOrcid.set(orcidKey, existing);
+        }
+        continue;
+      }
+    }
+
+    const likelyMatch = deduped.find((existing) => {
+      const existingOrcid = cleanString(existing?.orcid ?? '').toLowerCase();
+      const hasConflictingOrcid = existingOrcid && orcidKey && existingOrcid !== orcidKey;
+
+      if (hasConflictingOrcid) {
+        return false;
+      }
+
+      return authorsLikelyMatch(existing, author);
+    });
+
+    if (likelyMatch) {
+      if (!likelyMatch.orcid && author.orcid) {
+        likelyMatch.orcid = author.orcid;
+      }
+      if (!likelyMatch.affiliation && author.affiliation) {
+        likelyMatch.affiliation = author.affiliation;
+      }
+
+      const mergedOrcidKey = cleanString(likelyMatch?.orcid ?? '').toLowerCase();
+      if (mergedOrcidKey && !byOrcid.has(mergedOrcidKey)) {
+        byOrcid.set(mergedOrcidKey, likelyMatch);
+      }
+      continue;
+    }
+
+    if (orcidKey && byOrcid.has(orcidKey)) {
+      const existing = byOrcid.get(orcidKey);
+      if (!existing.affiliation && author.affiliation) {
+        existing.affiliation = author.affiliation;
+      }
+      continue;
+    }
+
     const key = [
       cleanString(author?.givenNames ?? '').toLowerCase(),
       cleanString(author?.familyNames ?? '').toLowerCase(),
@@ -1139,12 +1696,78 @@ function dedupeAuthors(authors) {
     }
 
     seen.add(key);
-    deduped.push(author);
+    const normalizedAuthor = { ...author };
+    deduped.push(normalizedAuthor);
+
+    if (orcidKey) {
+      byOrcid.set(orcidKey, normalizedAuthor);
+    }
+
+    if (nameKey !== '|') {
+      byName.set(nameKey, normalizedAuthor);
+    }
   }
 
   return deduped;
 }
 
+function orderAuthorsByContributorRank(authors, contributorAuthors) {
+  const normalizedAuthors = normalizeAuthors(Array.isArray(authors) ? authors : []);
+  const normalizedContributors = normalizeAuthors(Array.isArray(contributorAuthors) ? contributorAuthors : []);
+
+  if (normalizedContributors.length === 0 || normalizedAuthors.length <= 1) {
+    return normalizedAuthors;
+  }
+
+  const contributorOrcidIndex = new Map();
+  const contributorNameKeyIndex = new Map();
+
+  normalizedContributors.forEach((contributorAuthor, index) => {
+    const orcidKey = cleanString(contributorAuthor?.orcid ?? '').toLowerCase();
+    if (orcidKey && !contributorOrcidIndex.has(orcidKey)) {
+      contributorOrcidIndex.set(orcidKey, index);
+    }
+
+    for (const key of authorAltNameKeys(contributorAuthor)) {
+      if (!contributorNameKeyIndex.has(key)) {
+        contributorNameKeyIndex.set(key, index);
+      }
+    }
+  });
+
+  const ranked = normalizedAuthors.map((author, originalIndex) => {
+    const orcidKey = cleanString(author?.orcid ?? '').toLowerCase();
+    if (orcidKey && contributorOrcidIndex.has(orcidKey)) {
+      return { author, originalIndex, rank: contributorOrcidIndex.get(orcidKey) };
+    }
+
+    const nameRanks = authorAltNameKeys(author)
+      .map((key) => contributorNameKeyIndex.get(key))
+      .filter((value) => Number.isInteger(value));
+
+    if (nameRanks.length > 0) {
+      return { author, originalIndex, rank: Math.min(...nameRanks) };
+    }
+
+    const heuristicIndex = normalizedContributors.findIndex((contributorAuthor) => authorsLikelyMatch(author, contributorAuthor));
+    if (heuristicIndex >= 0) {
+      return { author, originalIndex, rank: heuristicIndex };
+    }
+
+    return { author, originalIndex, rank: Number.POSITIVE_INFINITY };
+  });
+
+  ranked.sort((left, right) => {
+    if (left.rank !== right.rank) {
+      return left.rank - right.rank;
+    }
+
+    return left.originalIndex - right.originalIndex;
+  });
+
+  return ranked.map((entry) => entry.author);
+}
+
 function isAutomatedContributor(contributor, profile) {
   const login = cleanString(profile?.login ?? contributor?.login ?? '').toLowerCase();
   const contributorType = cleanString(contributor?.type ?? '').toLowerCase();
@@ -1163,4 +1786,4 @@ function isAutomatedContributor(contributor, profile) {
   }
 
   return /(^|[-_])(github-actions|dependabot|copilot|codex|claude|swe-agent)([-_]|$)/.test(login);
-}
\ No newline at end of file
+}
diff --git a/src/services/metadataComparison.js b/src/services/metadataComparison.js
new file mode 100644
index 0000000..fd2fd9e
--- /dev/null
+++ b/src/services/metadataComparison.js
@@ -0,0 +1,27 @@
+import { runMetadataValidators } from './metadataValidators.js';
+
+export function compareExistingMetadataFiles(context) {
+  const comparisons = [];
+
+  if (context.fileValidationSummary?.citation?.present && context.citationForComparison) {
+    comparisons.push(
+      ...runMetadataValidators({
+        file: 'CITATION.cff',
+        metadata: context.citationForComparison,
+        context,
+      }),
+    );
+  }
+
+  if (context.fileValidationSummary?.zenodo?.present && context.zenodoForComparison) {
+    comparisons.push(
+      ...runMetadataValidators({
+        file: '.zenodo.json',
+        metadata: context.zenodoForComparison,
+        context,
+      }),
+    );
+  }
+
+  return comparisons;
+}
diff --git a/src/services/metadataReview.js b/src/services/metadataReview.js
new file mode 100644
index 0000000..f2df5b6
--- /dev/null
+++ b/src/services/metadataReview.js
@@ -0,0 +1,288 @@
+function createFinding({
+  id,
+  status,
+  severity,
+  category,
+  file,
+  field,
+  message,
+  recommendation,
+  action,
+}) {
+  return {
+    id,
+    status,
+    severity,
+    category,
+    file,
+    field,
+    message,
+    recommendation,
+    action,
+  };
+}
+
+function fileLabelFromSource(source) {
+  if (source === 'citation') {
+    return 'CITATION.cff';
+  }
+
+  if (source === 'zenodo') {
+    return '.zenodo.json';
+  }
+
+  return '';
+}
+
+function summarizeFindings(findings) {
+  const counts = {
+    correct: 0,
+    missing: 0,
+    outdated: 0,
+    invalid: 0,
+  };
+
+  for (const finding of findings) {
+    if (Object.prototype.hasOwnProperty.call(counts, finding.status)) {
+      counts[finding.status] += 1;
+    }
+  }
+
+  return {
+    total: findings.length,
+    byStatus: counts,
+  };
+}
+
+function buildRecommendations(findings, fileValidationSummary) {
+  const hasInvalid = findings.some((finding) => finding.status === 'invalid');
+  const hasOutdated = findings.some((finding) => finding.status === 'outdated');
+  const hasMissing = findings.some((finding) => finding.status === 'missing');
+
+  const citationNeedsRegenerate = findings.some(
+    (finding) => finding.file === 'CITATION.cff' && finding.action === 'regenerate-file',
+  );
+  const zenodoNeedsRegenerate = findings.some(
+    (finding) => finding.file === '.zenodo.json' && finding.action === 'regenerate-file',
+  );
+
+  const canKeepCurrentFiles = !hasInvalid && !hasOutdated && !hasMissing;
+  const canUpdateSpecificFields = !hasInvalid && (hasOutdated || hasMissing);
+  const shouldGenerateNewFiles = hasInvalid
+    || !fileValidationSummary?.citation?.present
+    || !fileValidationSummary?.zenodo?.present;
+
+  const actions = [];
+
+  if (canKeepCurrentFiles) {
+    actions.push('Keep current files as-is. Metadata is already consistent with repository state.');
+  }
+
+  if (canUpdateSpecificFields) {
+    actions.push('Update specific outdated or missing fields without replacing the whole files.');
+  }
+
+  if (shouldGenerateNewFiles) {
+    actions.push('Generate fresh metadata files for invalid or missing files.');
+  }
+
+  actions.push('Import review never overwrites repository files automatically; you choose what to update.');
+
+  return {
+    canKeepCurrentFiles,
+    canUpdateSpecificFields,
+    shouldGenerateNewFiles,
+    citationNeedsRegenerate,
+    zenodoNeedsRegenerate,
+    actions,
+  };
+}
+
+function ruleCitationFileState(context) {
+  const citation = context.fileValidationSummary?.citation;
+  if (!citation?.present) {
+    return createFinding({
+      id: 'citation-missing',
+      status: 'missing',
+      severity: 'medium',
+      category: 'file-state',
+      file: 'CITATION.cff',
+      field: '',
+      message: 'CITATION.cff was not found in the repository.',
+      recommendation: 'Generate CITATION.cff or add the required fields manually.',
+      action: 'generate-file',
+    });
+  }
+
+  if (!citation.valid) {
+    return createFinding({
+      id: 'citation-invalid',
+      status: 'invalid',
+      severity: 'high',
+      category: 'schema',
+      file: 'CITATION.cff',
+      field: '',
+      message: `CITATION.cff is invalid: ${(citation.errors || []).join(' | ')}`,
+      recommendation: 'Fix validation errors first; regenerate file if many fields are broken.',
+      action: 'regenerate-file',
+    });
+  }
+
+  return createFinding({
+    id: 'citation-valid',
+    status: 'correct',
+    severity: 'low',
+    category: 'file-state',
+    file: 'CITATION.cff',
+    field: '',
+    message: 'CITATION.cff exists and passes schema validation.',
+    recommendation: 'Keep file and only update changed fields when needed.',
+    action: 'keep-file',
+  });
+}
+
+function ruleZenodoFileState(context) {
+  const zenodo = context.fileValidationSummary?.zenodo;
+  if (!zenodo?.present) {
+    return createFinding({
+      id: 'zenodo-missing',
+      status: 'missing',
+      severity: 'medium',
+      category: 'file-state',
+      file: '.zenodo.json',
+      field: '',
+      message: '.zenodo.json was not found in the repository.',
+      recommendation: 'Generate .zenodo.json or add required fields manually.',
+      action: 'generate-file',
+    });
+  }
+
+  if (!zenodo.valid) {
+    return createFinding({
+      id: 'zenodo-invalid',
+      status: 'invalid',
+      severity: 'high',
+      category: 'schema',
+      file: '.zenodo.json',
+      field: '',
+      message: `.zenodo.json is invalid: ${(zenodo.errors || []).join(' | ')}`,
+      recommendation: 'Fix validation errors first; regenerate file if many fields are broken.',
+      action: 'regenerate-file',
+    });
+  }
+
+  return createFinding({
+    id: 'zenodo-valid',
+    status: 'correct',
+    severity: 'low',
+    category: 'file-state',
+    file: '.zenodo.json',
+    field: '',
+    message: '.zenodo.json exists and passes schema validation.',
+    recommendation: 'Keep file and only update changed fields when needed.',
+    action: 'keep-file',
+  });
+}
+
+function warningToField(code) {
+  if (code === 'version-mismatch' || code === 'cross-file-version-mismatch') return 'version';
+  if (code === 'date-mismatch') return 'publicationDate';
+  if (code === 'repository-url-mismatch') return 'repositoryCode';
+  if (code === 'license-mismatch') return 'license';
+  if (code === 'missing-version') return 'version';
+  return '';
+}
+
+function warningToStatus(code) {
+  if (code === 'missing-version') {
+    return 'missing';
+  }
+
+  return 'outdated';
+}
+
+function warningToAction(code) {
+  if (code === 'missing-version') {
+    return 'update-field';
+  }
+
+  return 'update-field';
+}
+
+function warningToRecommendation(code) {
+  if (code === 'missing-version') {
+    return 'Set version from latest release tag or add it manually if release data is unavailable.';
+  }
+
+  return 'Update the field to match current repository metadata.';
+}
+
+function ruleRepositoryConsistencyWarnings(context) {
+  const trackedCodes = new Set([
+    'version-mismatch',
+    'cross-file-version-mismatch',
+    'date-mismatch',
+    'repository-url-mismatch',
+    'license-mismatch',
+    'missing-version',
+  ]);
+
+  const findings = [];
+  const seen = new Set();
+
+  for (const warning of context.warnings || []) {
+    const code = String(warning?.code ?? '');
+    if (!trackedCodes.has(code)) {
+      continue;
+    }
+
+    const source = String(warning?.source ?? '');
+    const key = `${code}|${source}|${warning?.message ?? ''}`;
+    if (seen.has(key)) {
+      continue;
+    }
+    seen.add(key);
+
+    findings.push(createFinding({
+      id: `consistency-${seen.size}`,
+      status: warningToStatus(code),
+      severity: code === 'missing-version' ? 'high' : 'medium',
+      category: 'consistency',
+      file: fileLabelFromSource(source),
+      field: warningToField(code),
+      message: String(warning?.message ?? 'Metadata consistency issue detected.'),
+      recommendation: warningToRecommendation(code),
+      action: warningToAction(code),
+    }));
+  }
+
+  return findings;
+}
+
+export const defaultMetadataReviewRules = [
+  ruleCitationFileState,
+  ruleZenodoFileState,
+  ruleRepositoryConsistencyWarnings,
+];
+
+export function runMetadataReviewPipeline(context, rules = defaultMetadataReviewRules) {
+  const findings = [];
+
+  for (const rule of rules) {
+    const result = rule(context);
+    if (Array.isArray(result)) {
+      findings.push(...result.filter(Boolean));
+    } else if (result) {
+      findings.push(result);
+    }
+  }
+
+  const summary = summarizeFindings(findings);
+  const recommendations = buildRecommendations(findings, context.fileValidationSummary);
+
+  return {
+    findings,
+    summary,
+    recommendations,
+  };
+}
diff --git a/src/services/metadataValidators.js b/src/services/metadataValidators.js
new file mode 100644
index 0000000..8cb0408
--- /dev/null
+++ b/src/services/metadataValidators.js
@@ -0,0 +1,283 @@
+/**
+ * @typedef {'identical' | 'different' | 'missing' | 'cannot determine'} ValidationStatus
+ */
+
+/**
+ * @typedef {Object} ValidationResult
+ * @property {string} file
+ * @property {string} field
+ * @property {ValidationStatus} status
+ * @property {string} currentValue
+ * @property {string} githubValue
+ * @property {string} recommendation
+ */
+
+function cleanString(value) {
+  return String(value ?? '').trim();
+}
+
+function normalizeUrl(value) {
+  const text = cleanString(value);
+  if (!text) {
+    return '';
+  }
+
+  return text.replace(/^git\+/, '').replace(/\.git$/i, '').replace(/\/+$/, '').toLowerCase();
+}
+
+function normalizeDate(value) {
+  return cleanString(value).split('T')[0];
+}
+
+function normalizeVersion(value) {
+  return cleanString(value).toLowerCase().replace(/^v(?=\d)/, '');
+}
+
+function authorDisplayName(author) {
+  const given = cleanString(author?.givenNames ?? author?.['given-names'] ?? '');
+  const family = cleanString(author?.familyNames ?? author?.['family-names'] ?? '');
+  const name = cleanString(author?.name ?? '');
+
+  if (name) {
+    return name;
+  }
+
+  return [given, family].filter(Boolean).join(' ').trim();
+}
+
+function normalizeAuthorList(authors) {
+  if (!Array.isArray(authors)) {
+    return [];
+  }
+
+  return authors
+    .map((author) => authorDisplayName(author).toLowerCase())
+    .filter(Boolean)
+    .sort();
+}
+
+function normalizeKeywordList(keywords) {
+  if (!Array.isArray(keywords)) {
+    return [];
+  }
+
+  return keywords.map((item) => cleanString(item).toLowerCase()).filter(Boolean).sort();
+}
+
+function determineStatus({ currentValue, githubValue, canDetermine }) {
+  if (!canDetermine) {
+    return 'cannot determine';
+  }
+
+  if (!cleanString(currentValue)) {
+    return 'missing';
+  }
+
+  if (currentValue === githubValue) {
+    return 'identical';
+  }
+
+  return 'different';
+}
+
+function createValidationResult({
+  file,
+  field,
+  currentValue,
+  githubValue,
+  canDetermine = true,
+  recommendations = {},
+}) {
+  const status = determineStatus({ currentValue, githubValue, canDetermine });
+
+  const recommendation =
+    recommendations[status]
+    ?? (status === 'identical'
+      ? 'No update needed.'
+      : status === 'cannot determine'
+        ? 'Cannot determine from live GitHub metadata; review manually.'
+        : status === 'missing'
+          ? `Add ${field} from current metadata sources.`
+          : `Review and update ${field} to match current repository metadata.`);
+
+  return {
+    file,
+    field,
+    status,
+    currentValue,
+    githubValue,
+    recommendation,
+  };
+}
+
+export function validateVersion({ file, metadata, context }) {
+  const currentValue = normalizeVersion(metadata?.version);
+  const githubValue = normalizeVersion(context.releaseData?.tag_name);
+
+  return createValidationResult({
+    file,
+    field: 'version',
+    currentValue,
+    githubValue,
+    canDetermine: Boolean(githubValue),
+    recommendations: {
+      different: 'Update version to latest release.',
+      missing: 'Add version from latest release tag.',
+    },
+  });
+}
+
+export function validateRepositoryUrl({ file, metadata, context }) {
+  const currentValue = normalizeUrl(metadata?.repositoryCode);
+  const githubValue = normalizeUrl(context.repoData?.html_url);
+
+  return createValidationResult({
+    file,
+    field: 'repository-code',
+    currentValue,
+    githubValue,
+    canDetermine: Boolean(githubValue),
+    recommendations: {
+      different: 'Repository was renamed. Update repository-code.',
+      missing: 'Add repository-code from current GitHub URL.',
+    },
+  });
+}
+
+export function validateLicense({ file, metadata, context }) {
+  const currentValue = cleanString(metadata?.license).toUpperCase();
+  const githubValue = cleanString(context.repoData?.license?.spdx_id).toUpperCase();
+
+  return createValidationResult({
+    file,
+    field: 'license',
+    currentValue,
+    githubValue,
+    canDetermine: Boolean(githubValue),
+    recommendations: {
+      different: 'Review repository license and align citation metadata if needed.',
+      missing: 'Add repository SPDX license to metadata.',
+    },
+  });
+}
+
+export function validateReleaseDate({ file, metadata, context }) {
+  const field = file === '.zenodo.json' ? 'publication_date' : 'date-released';
+  const currentValue = normalizeDate(metadata?.publicationDate);
+  const githubValue = normalizeDate(context.releaseData?.published_at);
+
+  return createValidationResult({
+    file,
+    field,
+    currentValue,
+    githubValue,
+    canDetermine: Boolean(githubValue),
+    recommendations: {
+      different: 'Update release date to match latest GitHub release date.',
+      missing: 'Add latest release date to metadata.',
+    },
+  });
+}
+
+export function validateAuthors({ file, metadata, context }) {
+  const currentValue = normalizeAuthorList(metadata?.authors).join(', ');
+  const githubValue = normalizeAuthorList(context.contributorLookupAuthors).join(', ');
+
+  return createValidationResult({
+    file,
+    field: 'authors',
+    currentValue,
+    githubValue,
+    canDetermine: Boolean(githubValue),
+    recommendations: {
+      different: 'Review author list and update contributor attribution as needed.',
+      missing: 'Add authors from repository contributors or known citation authors.',
+    },
+  });
+}
+
+export function validateORCID({ file, metadata }) {
+  const authors = Array.isArray(metadata?.authors) ? metadata.authors : [];
+  const currentWithOrcid = authors.filter((author) => cleanString(author?.orcid)).length;
+  const currentValue = String(currentWithOrcid);
+  const githubValue = '';
+
+  return createValidationResult({
+    file,
+    field: 'orcid',
+    currentValue,
+    githubValue,
+    canDetermine: false,
+    recommendations: {
+      'cannot determine': 'ORCID cannot be determined from GitHub metadata alone; review manually.',
+      missing: 'Add ORCID IDs for authors when available.',
+    },
+  });
+}
+
+export function validateDOI({ file, metadata }) {
+  const currentValue = cleanString(metadata?.doi);
+  const githubValue = '';
+
+  return createValidationResult({
+    file,
+    field: 'doi',
+    currentValue,
+    githubValue,
+    canDetermine: false,
+    recommendations: {
+      'cannot determine': 'DOI cannot be determined from GitHub metadata alone; review manually.',
+      missing: 'Add DOI if you have an archival DOI (for example from Zenodo).',
+    },
+  });
+}
+
+export function validateKeywords({ file, metadata, context }) {
+  const currentValue = normalizeKeywordList(metadata?.keywords).join(', ');
+  const githubValue = normalizeKeywordList(context.repoData?.topics).join(', ');
+
+  return createValidationResult({
+    file,
+    field: 'keywords',
+    currentValue,
+    githubValue,
+    canDetermine: Boolean(githubValue),
+    recommendations: {
+      different: 'Review keywords and align with repository topics where appropriate.',
+      missing: 'Add keywords to improve discoverability.',
+    },
+  });
+}
+
+export function validateAbstract({ file, metadata, context }) {
+  const currentValue = cleanString(metadata?.abstract);
+  const githubValue = cleanString(context.repoData?.description);
+
+  return createValidationResult({
+    file,
+    field: 'abstract',
+    currentValue,
+    githubValue,
+    canDetermine: Boolean(githubValue),
+    recommendations: {
+      different: 'Review abstract text against repository description and update if outdated.',
+      missing: 'Add an abstract/description for citation clarity.',
+    },
+  });
+}
+
+export const DEFAULT_METADATA_VALIDATORS = [
+  validateVersion,
+  validateRepositoryUrl,
+  validateLicense,
+  validateReleaseDate,
+  validateAuthors,
+  validateORCID,
+  validateDOI,
+  validateKeywords,
+  validateAbstract,
+];
+
+export function runMetadataValidators({ file, metadata, context, validators = DEFAULT_METADATA_VALIDATORS }) {
+  return validators.map((validator) => validator({ file, metadata, context }));
+}
diff --git a/src/services/orcidSearch.js b/src/services/orcidSearch.js
new file mode 100644
index 0000000..62d0905
--- /dev/null
+++ b/src/services/orcidSearch.js
@@ -0,0 +1,118 @@
+function quoteQueryValue(value) {
+  return `"${String(value ?? '').replace(/"/g, '\\"').trim()}"`;
+}
+
+function buildOrcidQuery({ givenNames, familyNames, affiliation }) {
+  const parts = [];
+  const given = String(givenNames ?? '').trim();
+  const family = String(familyNames ?? '').trim();
+  const org = String(affiliation ?? '').trim();
+
+  if (given) {
+    parts.push(`given-names:${quoteQueryValue(given)}`);
+  }
+
+  if (family) {
+    parts.push(`family-name:${quoteQueryValue(family)}`);
+  }
+
+  if (org) {
+    parts.push(`affiliation-org-name:${quoteQueryValue(org)}`);
+  }
+
+  return parts.join(' AND ');
+}
+
+function normalizeCandidate(result) {
+  const orcidId = String(result?.['orcid-id'] ?? '').trim();
+  if (!orcidId) {
+    return null;
+  }
+
+  const givenNames = String(result?.['given-names'] ?? '').trim();
+  const familyNames = String(result?.['family-names'] ?? '').trim();
+  const affiliations = [];
+
+  for (const key of ['institution-name', 'employment-org-name', 'ror-org-name']) {
+    const rawValue = result?.[key];
+    if (Array.isArray(rawValue)) {
+      affiliations.push(...rawValue.map((item) => String(item ?? '').trim()).filter(Boolean));
+    } else if (rawValue) {
+      affiliations.push(String(rawValue).trim());
+    }
+  }
+
+  return {
+    orcid: `https://orcid.org/${orcidId}`,
+    givenNames,
+    familyNames,
+    affiliation: affiliations[0] ?? '',
+    label: [givenNames, familyNames].filter(Boolean).join(' ').trim() || orcidId,
+  };
+}
+
+function normalizeName(value) {
+  return String(value ?? '')
+    .toLowerCase()
+    .replace(/[^a-z0-9\s]/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+function affiliationLooksSimilar(left, right) {
+  const a = normalizeName(left);
+  const b = normalizeName(right);
+
+  if (!a || !b) {
+    return false;
+  }
+
+  return a === b || a.includes(b) || b.includes(a);
+}
+
+export function pickPreferredOrcidCandidate(author, candidates) {
+  const given = normalizeName(author?.givenNames);
+  const family = normalizeName(author?.familyNames);
+  const affiliation = String(author?.affiliation ?? '').trim();
+  const exactNameMatches = candidates.filter((candidate) => {
+    return normalizeName(candidate.givenNames) === given && normalizeName(candidate.familyNames) === family;
+  });
+
+  if (exactNameMatches.length === 1) {
+    return exactNameMatches[0];
+  }
+
+  if (exactNameMatches.length > 1 && affiliation) {
+    const exactWithAffiliation = exactNameMatches.filter((candidate) => affiliationLooksSimilar(candidate.affiliation, affiliation));
+    if (exactWithAffiliation.length === 1) {
+      return exactWithAffiliation[0];
+    }
+  }
+
+  return null;
+}
+
+export async function searchOrcidCandidates(author) {
+  const query = buildOrcidQuery(author);
+  if (!query) {
+    return [];
+  }
+
+  const response = await fetch(`https://pub.orcid.org/v3.0/expanded-search/?q=${encodeURIComponent(query)}`, {
+    headers: {
+      Accept: 'application/json',
+    },
+  });
+
+  if (!response.ok) {
+    throw new Error(`ORCID search failed: ${response.status} ${response.statusText}`);
+  }
+
+  const payload = await response.json();
+  const results = Array.isArray(payload?.['expanded-result']) ? payload['expanded-result'] : [];
+
+  return results
+    .map((result) => normalizeCandidate(result))
+    .filter(Boolean)
+    .slice(0, 5);
+}
\ No newline at end of file
diff --git a/src/services/zenodo.js b/src/services/zenodo.js
index 120916b..61d00fd 100644
--- a/src/services/zenodo.js
+++ b/src/services/zenodo.js
@@ -1,4 +1,18 @@
 export function toZenodoJson(metadata) {
+  const references = (Array.isArray(metadata.references) ? metadata.references : [])
+    .map((reference) => {
+      if (typeof reference === 'string') {
+        return reference.trim();
+      }
+
+      if (reference && typeof reference === 'object') {
+        return String(reference.doi || reference.url || reference.title || '').trim();
+      }
+
+      return '';
+    })
+    .filter(Boolean);
+
   const keywords = metadata.keywords.includes('imageomics')
     ? metadata.keywords
     : ['imageomics', ...metadata.keywords];
@@ -21,7 +35,7 @@ export function toZenodoJson(metadata) {
       license: metadata.license,
       publication_date: metadata.publicationDate,
       grants: metadata.grants.map((id) => ({ id })),
-      references: metadata.references,
+      references,
     },
     null,
     2,
diff --git a/src/services/zenodoValidation.js b/src/services/zenodoValidation.js
new file mode 100644
index 0000000..b2c648b
--- /dev/null
+++ b/src/services/zenodoValidation.js
@@ -0,0 +1,151 @@
+function cleanString(value) {
+  return String(value ?? '').trim();
+}
+
+function isValidIsoDate(value) {
+  const text = cleanString(value);
+  if (!text || !/^\d{4}-\d{2}-\d{2}$/.test(text)) {
+    return false;
+  }
+
+  const [yearText, monthText, dayText] = text.split('-');
+  const year = Number(yearText);
+  const month = Number(monthText);
+  const day = Number(dayText);
+
+  if (!Number.isInteger(year) || !Number.isInteger(month) || !Number.isInteger(day)) {
+    return false;
+  }
+
+  const date = new Date(Date.UTC(year, month - 1, day));
+  return date.getUTCFullYear() === year
+    && date.getUTCMonth() === month - 1
+    && date.getUTCDate() === day;
+}
+
+function formatReport({ isValid, errors, warnings, payload }) {
+  const lines = [
+    'OpenCite Metadata Validation Report',
+    '=================================',
+    `Status: ${isValid ? 'PASS' : 'FAIL'}`,
+    '',
+    'File: .zenodo.json',
+    `Generated: ${new Date().toISOString()}`,
+    '',
+  ];
+
+  if (errors.length > 0) {
+    lines.push('Errors:');
+    for (const error of errors) {
+      lines.push(`- ${error}`);
+    }
+    lines.push('');
+  }
+
+  if (warnings.length > 0) {
+    lines.push('Warnings:');
+    for (const warning of warnings) {
+      lines.push(`- ${warning}`);
+    }
+    lines.push('');
+  }
+
+  lines.push('Summary:');
+  lines.push(`- title: ${cleanString(payload.title) ? 'present' : 'missing'}`);
+  lines.push(`- version: ${cleanString(payload.version) ? 'present' : 'missing'}`);
+  lines.push(`- publication_date: ${cleanString(payload.publication_date) ? payload.publication_date : 'missing'}`);
+  lines.push(`- creators: ${Array.isArray(payload.creators) ? payload.creators.length : 0}`);
+  lines.push(`- grants: ${Array.isArray(payload.grants) ? payload.grants.length : 0}`);
+
+  return lines.join('\n');
+}
+
+export function validateZenodoJsonText(text) {
+  const errors = [];
+  const warnings = [];
+  const allowedUploadTypes = new Set([
+    'publication',
+    'poster',
+    'presentation',
+    'dataset',
+    'image',
+    'video',
+    'software',
+    'lesson',
+    'physicalobject',
+    'other',
+  ]);
+  const grantPattern = /^[A-Za-z0-9.-]+::[A-Za-z0-9.-]+$/;
+
+  let payload;
+  try {
+    payload = JSON.parse(String(text ?? ''));
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    errors.push(`Invalid JSON: ${message}`);
+    const report = formatReport({ isValid: false, errors, warnings, payload: {} });
+    return { isValid: false, errors, warnings, payload: null, report };
+  }
+
+  const title = cleanString(payload.title);
+  const version = cleanString(payload.version);
+  const publicationDate = cleanString(payload.publication_date);
+  const uploadType = cleanString(payload.upload_type);
+
+  if (!title) {
+    errors.push('title is required.');
+  }
+
+  if (!version) {
+    errors.push('version is required.');
+  }
+
+  if (!publicationDate) {
+    errors.push('publication_date is required.');
+  } else if (!isValidIsoDate(publicationDate)) {
+    errors.push('publication_date must be a real date in YYYY-MM-DD format.');
+  }
+
+  if (!uploadType) {
+    errors.push('upload_type is required.');
+  } else if (!allowedUploadTypes.has(uploadType)) {
+    warnings.push(`upload_type \"${uploadType}\" is not a common Zenodo upload_type value.`);
+  }
+
+  if (!Array.isArray(payload.creators) || payload.creators.length === 0) {
+    errors.push('creators must include at least one creator entry.');
+  } else {
+    const missingCreatorNames = payload.creators.some((creator) => !cleanString(creator?.name));
+    if (missingCreatorNames) {
+      errors.push('each creator entry must include a non-empty name.');
+    }
+  }
+
+  if (!Array.isArray(payload.grants)) {
+    warnings.push('grants should be an array of objects containing an id field.');
+  } else {
+    for (let index = 0; index < payload.grants.length; index += 1) {
+      const grant = payload.grants[index];
+      const grantId = cleanString(grant?.id);
+      if (!grantId) {
+        warnings.push(`grants[${index}] is missing id.`);
+        continue;
+      }
+
+      if (!grantPattern.test(grantId)) {
+        errors.push(`grants[${index}].id must match <funder-code>::<grant-number>.`);
+      }
+    }
+  }
+
+  const isValid = errors.length === 0;
+  const report = formatReport({ isValid, errors, warnings, payload });
+
+  return {
+    isValid,
+    errors,
+    warnings,
+    payload,
+    report,
+  };
+}
diff --git a/src/styles.css b/src/styles.css
index 06f8969..8efdd89 100644
--- a/src/styles.css
+++ b/src/styles.css
@@ -1,81 +1,13 @@
 :root {
-  font-family: 'Segoe UI', -apple-system, BlinkMacSystemFont, system-ui, sans-serif;
-  --slate-1: #fcfcfd;
-  --slate-2: #f9f9fb;
-  --slate-6: #d9d9e0;
-  --slate-7: #cdced6;
-  --slate-11: #60646c;
-  --slate-12: #1c2024;
-  --teal-9: #245963;
-  --teal-10: #114953;
-  --teal-3: #e7f4f7;
-  --lime-9: #7eac55;
-  --lime-10: #73a049;
-  --lime-3: #e9f7de;
-  --app-bg-1: var(--slate-1);
-  --app-bg-2: var(--slate-2);
-  --hero-glow-teal: rgba(139, 187, 197, 0.24);
-  --hero-glow-lime: rgba(126, 172, 85, 0.14);
-  --text-primary: var(--slate-12);
-  --text-secondary: var(--slate-11);
-  --surface-card: rgba(252, 252, 253, 0.95);
-  --surface-input: var(--slate-1);
-  --surface-muted: var(--slate-2);
-  --border-soft: var(--slate-6);
-  --border-strong: var(--slate-7);
-  --on-primary: #fafdfe;
-  --focus-ring: rgba(139, 187, 197, 0.35);
-  --secondary-button-bg: var(--slate-1);
-  --secondary-button-text: var(--teal-10);
-  --secondary-button-border: var(--teal-9);
-  --secondary-button-hover: var(--teal-3);
-  --link-color: var(--teal-10);
-  --link-color-hover: var(--teal-9);
-  --selection-bg: var(--lime-3);
-  --status-success: #2f4022;
-  --status-success-bg: #e9f7de;
-  --status-error: #7a2d2d;
-  --status-error-bg: #fff1f1;
-  --status-loading: var(--teal-10);
-  --status-loading-bg: #e7f4f7;
-  color: var(--text-primary);
+  font-family: Inter, system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+  color: #e8edf2;
   background:
-    radial-gradient(circle at top right, var(--hero-glow-teal), transparent 38%),
-    radial-gradient(circle at top left, var(--hero-glow-lime), transparent 42%),
-    linear-gradient(180deg, var(--app-bg-1) 0%, var(--app-bg-2) 100%);
+    radial-gradient(circle at top, rgba(92, 124, 250, 0.24), transparent 36%),
+    linear-gradient(180deg, #0f172a 0%, #111827 100%);
   line-height: 1.5;
   font-weight: 400;
 }
 
-:root[data-theme='dark'] {
-  --app-bg-1: #1c2024;
-  --app-bg-2: #183136;
-  --hero-glow-teal: rgba(36, 89, 99, 0.35);
-  --hero-glow-lime: rgba(115, 160, 73, 0.24);
-  --text-primary: #f9f9fb;
-  --text-secondary: #d9d9e0;
-  --surface-card: rgba(28, 32, 36, 0.93);
-  --surface-input: #1c2024;
-  --surface-muted: rgba(24, 49, 54, 0.82);
-  --border-soft: #60646c;
-  --border-strong: #80838d;
-  --on-primary: #fafdfe;
-  --focus-ring: rgba(170, 206, 214, 0.35);
-  --secondary-button-bg: rgba(24, 49, 54, 0.74);
-  --secondary-button-text: #e7f4f7;
-  --secondary-button-border: #8bbbc5;
-  --secondary-button-hover: #245963;
-  --link-color: #aaced6;
-  --link-color-hover: #bedbe2;
-  --selection-bg: #567c33;
-  --status-success: #cbe9b5;
-  --status-success-bg: rgba(47, 64, 34, 0.45);
-  --status-error: #ffb3b3;
-  --status-error-bg: rgba(122, 45, 45, 0.45);
-  --status-loading: #aaced6;
-  --status-loading-bg: rgba(36, 89, 99, 0.45);
-}
-
 * {
   box-sizing: border-box;
 }
@@ -99,27 +31,34 @@ textarea {
 }
 
 button {
-  border: 1px solid transparent;
+  border: 0;
   border-radius: 999px;
   padding: 0.9rem 1.25rem;
-  background: var(--teal-9);
-  color: var(--on-primary);
+  background: #f8fafc;
+  color: #0f172a;
   cursor: pointer;
-  transition: background-color 120ms ease, border-color 120ms ease, color 120ms ease;
 }
 
-button:hover {
-  background: var(--teal-10);
+button.secondary {
+  background: transparent;
+  color: #e8edf2;
+  border: 1px solid rgba(232, 237, 242, 0.2);
 }
 
-button.secondary {
-  background: var(--secondary-button-bg);
-  color: var(--secondary-button-text);
-  border-color: var(--secondary-button-border);
+button.loading-button {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.65rem;
 }
 
-button.secondary:hover {
-  background: var(--secondary-button-hover);
+.button-spinner {
+  width: 0.95rem;
+  height: 0.95rem;
+  border-radius: 999px;
+  border: 2px solid rgba(15, 23, 42, 0.18);
+  border-top-color: currentColor;
+  animation: spin 0.8s linear infinite;
+  flex: 0 0 auto;
 }
 
 .app-shell {
@@ -131,152 +70,180 @@ button.secondary:hover {
 
 .card {
   width: min(920px, 100%);
-  background: var(--surface-card);
-  border: 1px solid var(--border-strong);
+  background: rgba(15, 23, 42, 0.72);
+  border: 1px solid rgba(148, 163, 184, 0.18);
   border-radius: 28px;
   padding: 32px;
-  box-shadow: 0 22px 60px rgba(28, 32, 36, 0.1);
+  box-shadow: 0 24px 80px rgba(2, 6, 23, 0.38);
   backdrop-filter: blur(14px);
 }
 
 .hero {
   margin-bottom: 24px;
-  padding: 22px;
-  border: 1px solid var(--border-soft);
-  border-radius: 20px;
-  background:
-    radial-gradient(circle at 85% 12%, var(--hero-glow-teal), transparent 40%),
-    linear-gradient(180deg, var(--surface-card), var(--surface-muted));
 }
 
-.hero-header {
+.page-tabs {
   display: flex;
-  justify-content: space-between;
-  align-items: center;
-  gap: 12px;
-  margin-bottom: 8px;
+  flex-wrap: wrap;
+  gap: 10px;
+  margin-bottom: 18px;
 }
 
-.theme-toggle {
-  padding: 0.45rem 0.9rem;
-  font-size: 0.85rem;
+.tab-active {
+  background: #f8fafc;
+  color: #0f172a;
+  border: 1px solid rgba(15, 23, 42, 0.15);
 }
 
-.hero-import {
-  margin-top: 16px;
-  background: var(--teal-9);
+.export-notice {
+  margin-bottom: 20px;
+  padding: 16px 18px;
+  border-radius: 18px;
+  border: 1px solid transparent;
+  box-shadow: 0 12px 40px rgba(2, 6, 23, 0.18);
 }
 
-.eyebrow {
-  margin: 0 0 8px;
-  text-transform: uppercase;
-  letter-spacing: 0.18em;
-  font-size: 0.75rem;
-  color: var(--lime-10);
-  font-weight: 700;
+.export-notice strong {
+  display: block;
+  margin-bottom: 8px;
 }
 
-h1,
-h2,
-p {
-  margin-top: 0;
+.export-notice ul {
+  margin: 0;
+  padding-left: 18px;
 }
 
-h1 {
-  margin-bottom: 12px;
-  font-size: clamp(2rem, 4vw, 3.2rem);
-  line-height: 1.05;
+.export-notice-warning {
+  background: rgba(113, 63, 18, 0.34);
+  border-color: rgba(251, 191, 36, 0.34);
 }
 
-.lede {
-  margin: 0;
-  max-width: 62ch;
-  color: var(--text-secondary);
+.export-notice-info {
+  background: rgba(30, 64, 175, 0.24);
+  border-color: rgba(147, 197, 253, 0.3);
 }
 
 .import-panel {
-  margin-top: 22px;
+  margin-bottom: 20px;
+  padding: 20px;
+  border-radius: 22px;
+  background: rgba(2, 6, 23, 0.28);
+  border: 1px solid rgba(148, 163, 184, 0.14);
+}
+
+.import-feedback {
   display: grid;
-  gap: 10px;
-  padding: 18px;
-  border: 1px solid var(--border-soft);
-  border-radius: 18px;
-  background: var(--surface-muted);
+  gap: 12px;
+  margin-top: 14px;
 }
 
-.import-panel-header {
-  display: flex;
-  align-items: flex-start;
-  gap: 10px;
+.feedback-block {
+  border-radius: 16px;
+  padding: 14px 16px;
 }
 
-.import-panel-header h2 {
-  margin-bottom: 4px;
+.feedback-block strong {
+  display: block;
+  margin-bottom: 8px;
 }
 
-.import-panel-header p {
+.feedback-block ul {
   margin: 0;
-  color: var(--text-secondary);
+  padding-left: 18px;
 }
 
-.icon-badge {
-  width: 1.9rem;
-  height: 1.9rem;
-  display: grid;
-  place-items: center;
-  border-radius: 50%;
-  background: var(--lime-3);
-  color: var(--lime-10);
-  font-weight: 700;
+.feedback-error {
+  background: rgba(127, 29, 29, 0.32);
+  border: 1px solid rgba(248, 113, 113, 0.3);
 }
 
-.import-example {
-  margin-top: -4px;
+.feedback-warning {
+  background: rgba(113, 63, 18, 0.32);
+  border: 1px solid rgba(251, 191, 36, 0.28);
 }
 
-.import-button {
-  justify-self: start;
+.feedback-review {
+  background: rgba(30, 64, 175, 0.24);
+  border: 1px solid rgba(147, 197, 253, 0.28);
+}
+
+.feedback-health {
+  background: rgba(22, 101, 52, 0.24);
+  border: 1px solid rgba(134, 239, 172, 0.32);
+}
+
+.feedback-comparison {
+  background: rgba(15, 23, 42, 0.36);
+  border: 1px solid rgba(148, 163, 184, 0.3);
+}
+
+.feedback-summary {
+  background: rgba(37, 99, 235, 0.2);
+  border: 1px solid rgba(147, 197, 253, 0.35);
 }
 
-.import-status {
+.comparison-list {
+  list-style: none;
   margin: 0;
-  padding: 0.55rem 0.75rem;
-  border-radius: 10px;
-  border: 1px solid var(--border-soft);
+  padding: 0;
+  display: grid;
+  gap: 10px;
 }
 
-.status-idle {
-  color: var(--text-secondary);
+.comparison-item {
+  padding: 10px 12px;
+  border: 1px solid rgba(148, 163, 184, 0.22);
+  border-radius: 12px;
+  background: rgba(2, 6, 23, 0.28);
 }
 
-.status-loading {
-  color: var(--status-loading);
-  background: var(--status-loading-bg);
+.comparison-header {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  gap: 10px;
+  margin-bottom: 6px;
 }
 
-.status-success {
-  color: var(--status-success);
-  background: var(--status-success-bg);
+.comparison-status {
+  font-size: 0.72rem;
+  font-weight: 700;
+  letter-spacing: 0.03em;
+  padding: 2px 8px;
+  border-radius: 999px;
+  border: 1px solid rgba(148, 163, 184, 0.35);
+  color: #e2e8f0;
 }
 
-.status-error {
-  color: var(--status-error);
-  background: var(--status-error-bg);
+.comparison-item p {
+  margin: 4px 0;
+  font-size: 0.9rem;
+  color: #dbeafe;
 }
 
-.pipeline-card {
-  margin-top: 18px;
-  border: 1px solid var(--border-soft);
-  border-radius: 18px;
-  padding: 16px;
-  background: var(--surface-card);
+.comparison-item p span {
+  font-weight: 700;
+  color: #f8fafc;
 }
 
-.pipeline-card h2 {
-  margin-bottom: 10px;
+.health-group {
+  margin-top: 12px;
+  padding-top: 10px;
+  border-top: 1px solid rgba(148, 163, 184, 0.22);
+}
+
+.health-group h3 {
+  margin: 0 0 8px;
+  font-size: 0.95rem;
+  color: #f8fafc;
+}
+
+.health-group ul {
+  margin: 0;
+  padding-left: 18px;
 }
 
-.pipeline-list {
+.health-list {
   list-style: none;
   margin: 0;
   padding: 0;
@@ -284,44 +251,132 @@ h1 {
   gap: 10px;
 }
 
-.pipeline-step {
+.health-item {
+  padding: 10px 12px;
+  border-radius: 12px;
+  border: 1px solid rgba(148, 163, 184, 0.24);
+  background: rgba(2, 6, 23, 0.28);
+}
+
+.health-item-header {
   display: flex;
   align-items: center;
-  gap: 10px;
+  gap: 8px;
+  margin-bottom: 6px;
 }
 
-.step-badge {
-  width: 1.55rem;
-  height: 1.55rem;
+.health-badge {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  min-width: 70px;
+  padding: 2px 8px;
   border-radius: 999px;
-  display: grid;
-  place-items: center;
-  font-size: 0.84rem;
-  border: 1px solid var(--border-strong);
+  font-size: 0.72rem;
+  font-weight: 700;
+  letter-spacing: 0.03em;
+  border: 1px solid rgba(148, 163, 184, 0.35);
+  color: #e2e8f0;
+}
+
+.health-badge-pass {
+  background: rgba(34, 197, 94, 0.2);
+  border-color: rgba(134, 239, 172, 0.5);
+  color: #bbf7d0;
+}
+
+.health-badge-warning {
+  background: rgba(245, 158, 11, 0.2);
+  border-color: rgba(253, 224, 71, 0.45);
+  color: #fde68a;
+}
+
+.health-badge-error {
+  background: rgba(239, 68, 68, 0.2);
+  border-color: rgba(252, 165, 165, 0.45);
+  color: #fecaca;
+}
+
+.health-item-description,
+.health-item-recommendation {
+  margin: 0;
+  color: #dbeafe;
+  font-size: 0.92rem;
+}
+
+.health-item-recommendation {
+  margin-top: 6px;
+}
+
+.health-item-recommendation span {
+  font-weight: 700;
+  color: #f8fafc;
+}
+
+.review-summary {
+  margin: 0 0 8px;
+  color: #dbeafe;
+  font-size: 0.92rem;
+}
+
+.eyebrow {
+  margin: 0 0 8px;
+  text-transform: uppercase;
+  letter-spacing: 0.18em;
+  font-size: 0.75rem;
+  color: #93c5fd;
 }
 
-.pipeline-step-complete {
-  color: var(--teal-9);
+h1,
+h2,
+p {
+  margin-top: 0;
 }
 
-.pipeline-step-complete .step-badge {
-  background: var(--teal-9);
-  color: var(--on-primary);
-  border-color: var(--teal-9);
+h1 {
+  margin-bottom: 12px;
+  font-size: clamp(2rem, 4vw, 3.2rem);
+  line-height: 1.05;
 }
 
-.pipeline-step-current {
-  color: var(--lime-10);
+.lede {
+  margin: 0;
+  max-width: 62ch;
+  color: #cbd5e1;
 }
 
-.pipeline-step-current .step-badge {
-  background: var(--lime-9);
-  color: var(--on-primary);
-  border-color: var(--lime-9);
+.learn-more-panel {
+  margin-bottom: 20px;
+  padding: 18px 20px;
+  border-radius: 20px;
+  background: rgba(2, 6, 23, 0.3);
+  border: 1px solid rgba(148, 163, 184, 0.16);
 }
 
-.pipeline-step-upcoming {
-  color: var(--text-secondary);
+.learn-more-panel h2 {
+  margin: 0 0 6px;
+  font-size: 1.15rem;
+}
+
+.learn-more-panel p {
+  margin: 0 0 10px;
+  color: #cbd5e1;
+}
+
+.learn-more-panel ul {
+  margin: 0;
+  padding-left: 18px;
+  display: grid;
+  gap: 6px;
+}
+
+.learn-more-panel a {
+  color: #93c5fd;
+}
+
+.learn-more-panel a:hover,
+.learn-more-panel a:focus-visible {
+  color: #bfdbfe;
 }
 
 .form-grid {
@@ -330,6 +385,48 @@ h1 {
   gap: 16px;
 }
 
+.form-section {
+  display: grid;
+  gap: 14px;
+  padding: 16px;
+  border-radius: 18px;
+  border: 1px solid rgba(148, 163, 184, 0.2);
+  background: rgba(2, 6, 23, 0.22);
+}
+
+.section-header h3 {
+  margin: 2px 0 0;
+  font-size: 1.02rem;
+  color: #f8fafc;
+}
+
+.section-step {
+  margin: 0;
+  font-size: 0.78rem;
+  font-weight: 700;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+  color: #93c5fd;
+}
+
+.section-lede {
+  margin: 6px 0 0;
+  font-size: 0.9rem;
+  color: #cbd5e1;
+}
+
+.section-grid {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: 16px;
+}
+
+.required-note {
+  margin: 0;
+  font-size: 0.85rem;
+  color: #cbd5e1;
+}
+
 label {
   display: grid;
   gap: 8px;
@@ -337,34 +434,66 @@ label {
 
 label span {
   font-size: 0.92rem;
-  color: var(--text-secondary);
+  color: #cbd5e1;
+}
+
+.field-error span {
+  color: #fecaca;
 }
 
 input,
 select,
 textarea {
   width: 100%;
-  border: 1px solid var(--border-strong);
+  border: 1px solid rgba(148, 163, 184, 0.22);
   border-radius: 16px;
-  background: var(--surface-input);
-  color: var(--text-primary);
+  background: rgba(15, 23, 42, 0.9);
+  color: #f8fafc;
   padding: 0.95rem 1rem;
-  transition: border-color 120ms ease, box-shadow 120ms ease;
 }
 
-input::placeholder,
-textarea::placeholder {
-  color: var(--text-secondary);
+select {
+  border-radius: 10px;
+  min-height: 48px;
+  line-height: 1.2;
+  padding-right: 2.4rem;
+  background-color: #0f172a;
+  appearance: none;
+  -webkit-appearance: none;
+  -moz-appearance: none;
+  background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='14' height='14' viewBox='0 0 20 20'%3E%3Cpath fill='%23cbd5e1' d='M5.5 7.5L10 12l4.5-4.5 1.4 1.4L10 14.8 4.1 8.9z'/%3E%3C/svg%3E");
+  background-repeat: no-repeat;
+  background-position: right 0.85rem center;
+  background-size: 0.9rem;
+}
+
+select option {
+  background-color: #0f172a;
+  color: #f8fafc;
+}
+
+select::-ms-expand {
+  display: none;
+}
+
+.compact-import {
+  margin-bottom: 22px;
+}
+
+.import-note {
+  margin: 10px 0 0;
+  color: #cbd5e1;
+  font-size: 0.9rem;
+}
+
+.input-error {
+  border-color: rgba(248, 113, 113, 0.85);
+  box-shadow: 0 0 0 1px rgba(248, 113, 113, 0.35);
 }
 
-input:focus,
-select:focus,
-textarea:focus,
-button:focus-visible,
-a:focus-visible {
-  outline: 2px solid transparent;
-  border-color: var(--teal-9);
-  box-shadow: 0 0 0 3px var(--focus-ring);
+.error-text {
+  color: #fca5a5;
+  font-size: 0.82rem;
 }
 
 textarea {
@@ -381,72 +510,112 @@ textarea {
   gap: 12px;
 }
 
+.authors-toolbar {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  justify-content: space-between;
+  gap: 8px;
+  margin-bottom: 10px;
+}
+
+.authors-toolbar small {
+  color: #cbd5e1;
+}
+
 .author-row {
   display: grid;
   gap: 8px;
+  padding: 12px;
+  border: 1px solid rgba(148, 163, 184, 0.2);
+  border-radius: 14px;
+  background: rgba(2, 6, 23, 0.2);
 }
 
-.author-row button {
-  justify-self: start;
+.author-row-header {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  justify-content: space-between;
+  gap: 8px;
 }
 
-.actions {
+.author-actions {
   display: flex;
   flex-wrap: wrap;
-  gap: 12px;
-  margin-top: 24px;
+  gap: 8px;
 }
 
-.notice-card {
-  margin-top: 16px;
-  padding: 14px 16px;
-  border-radius: 14px;
-  border: 1px solid var(--border-soft);
+.orcid-tools {
+  display: grid;
+  gap: 8px;
 }
 
-.notice-success {
-  background: var(--status-success-bg);
-  color: var(--status-success);
+.orcid-suggestions {
+  display: grid;
+  gap: 8px;
 }
 
-.notice-error {
-  background: var(--status-error-bg);
-  color: var(--status-error);
+.orcid-suggestion {
+  text-align: left;
+  border-radius: 16px;
 }
 
-.notice-title {
-  margin-bottom: 4px;
-  font-weight: 700;
+.author-actions button {
+  justify-self: start;
 }
 
-.notice-files {
-  margin-top: 6px;
-  font-size: 0.9rem;
+.icon-button {
+  min-width: 44px;
+  padding-left: 0.9rem;
+  padding-right: 0.9rem;
 }
 
-.metadata-cards {
-  margin-top: 20px;
-  display: grid;
-  grid-template-columns: repeat(2, minmax(0, 1fr));
+.actions {
+  display: flex;
+  flex-wrap: wrap;
   gap: 12px;
+  margin-top: 24px;
 }
 
-.metadata-card {
-  border: 1px solid var(--border-soft);
-  border-radius: 14px;
-  padding: 12px 14px;
-  background: var(--surface-card);
+.filename-note {
+  margin: 10px 0 0;
+  color: #cbd5e1;
+  font-size: 0.9rem;
 }
 
-.metadata-card h3 {
-  margin-top: 0;
-  margin-bottom: 8px;
-  color: var(--teal-10);
+.filename-note strong {
+  color: #f8fafc;
 }
 
-.metadata-card p {
-  margin: 4px 0;
-  color: var(--text-secondary);
+.grant-suggestions {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 8px;
+}
+
+.grant-reference-list {
+  margin: 0;
+  padding-left: 18px;
+  color: #cbd5e1;
+  display: grid;
+  gap: 4px;
+}
+
+@keyframes spin {
+  from {
+    transform: rotate(0deg);
+  }
+
+  to {
+    transform: rotate(360deg);
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .button-spinner {
+    animation: none;
+  }
 }
 
 .preview {
@@ -467,47 +636,9 @@ pre {
   word-break: break-word;
   border-radius: 20px;
   padding: 20px;
-  background: var(--surface-muted);
-  border: 1px solid var(--border-soft);
-  color: var(--text-primary);
-}
-
-small {
-  color: var(--text-secondary);
-}
-
-.app-footer {
-  margin-top: 28px;
-  padding-top: 18px;
-  border-top: 1px solid var(--border-soft);
-  display: grid;
-  gap: 8px;
-}
-
-.app-footer h3 {
-  margin: 0;
-}
-
-.app-footer p {
-  margin: 0;
-  color: var(--text-secondary);
-  font-size: 0.92rem;
-}
-
-.app-footer a {
-  color: var(--link-color);
-  font-weight: 600;
-  text-decoration-color: rgba(17, 73, 83, 0.35);
-}
-
-.app-footer a:hover {
-  color: var(--link-color-hover);
-  text-decoration-color: var(--link-color-hover);
-}
-
-::selection {
-  background: var(--selection-bg);
-  color: var(--text-primary);
+  background: rgba(2, 6, 23, 0.56);
+  border: 1px solid rgba(148, 163, 184, 0.14);
+  color: #bfdbfe;
 }
 
 @media (max-width: 720px) {
@@ -524,11 +655,7 @@ small {
     grid-template-columns: 1fr;
   }
 
-  .hero-header {
-    align-items: flex-start;
-  }
-
-  .metadata-cards {
+  .section-grid {
     grid-template-columns: 1fr;
   }
 }
diff --git a/src/utils/orcid.js b/src/utils/orcid.js
index a2562e5..7d40212 100644
--- a/src/utils/orcid.js
+++ b/src/utils/orcid.js
@@ -1,17 +1,110 @@
+const ORCID_ID_PATTERN = /\b(\d{4}-\d{4}-\d{4}-\d{3}[0-9X])\b/i;
+const ORCID_URL_PATTERN = /(?:https?:\/\/)?(?:www\.)?orcid\.org\/(\d{4}-\d{4}-\d{4}-\d{3}[0-9X])/i;
+
 export function normalizeOrcid(orcid) {
   const raw = String(orcid ?? '').trim();
-
   if (!raw) return '';
 
-  if (raw.startsWith('http://') || raw.startsWith('https://')) {
-    return raw;
+  const stripped = stripOrcidUrl(raw).toUpperCase();
+
+  if (stripped && isValidOrcidFormat(stripped)) {
+    return `https://orcid.org/${stripped}`;
   }
 
-  return `https://orcid.org/${raw}`;
+  return raw;
 }
 
-export function toZenodoOrcid(orcid) {
+export function stripOrcidUrl(orcid) {
   return String(orcid ?? '')
-    .replace(/^https?:\/\/(www\.)?orcid\.org\//, '')
+    .replace(/^(?:https?:\/\/)?(?:www\.)?orcid\.org\//i, '')
     .trim();
 }
+
+export function isValidOrcidFormat(orcid) {
+  const id = stripOrcidUrl(orcid).toUpperCase();
+  if (!id) {
+    return true;
+  }
+
+  if (!ORCID_ID_PATTERN.test(id)) {
+    return false;
+  }
+
+  const digits = id.replace(/-/g, '');
+  let total = 0;
+
+  for (let index = 0; index < 15; index += 1) {
+    const digit = Number(digits[index]);
+    if (!Number.isInteger(digit) || digit < 0 || digit > 9) {
+      return false;
+    }
+
+    total = (total + digit) * 2;
+  }
+
+  const remainder = total % 11;
+  const result = (12 - remainder) % 11;
+  const checkDigit = result === 10 ? 'X' : String(result);
+
+  return digits[15] === checkDigit;
+}
+
+export function extractOrcidFromText(value) {
+  const text = String(value ?? '').trim().replace(/[<>()]/g, ' ');
+  if (!text) {
+    return null;
+  }
+
+  const urlMatch = text.match(ORCID_URL_PATTERN);
+  if (urlMatch?.[1]) {
+    return normalizeOrcid(urlMatch[1].toUpperCase());
+  }
+
+  const idMatch = text.match(ORCID_ID_PATTERN);
+  if (idMatch?.[1]) {
+    return normalizeOrcid(idMatch[1].toUpperCase());
+  }
+
+  return null;
+}
+
+function extractOrcidFromUnknown(value) {
+  if (typeof value === 'string') {
+    return extractOrcidFromText(value);
+  }
+
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      const match = extractOrcidFromUnknown(item);
+      if (match) {
+        return match;
+      }
+    }
+
+    return null;
+  }
+
+  if (value && typeof value === 'object') {
+    for (const nestedValue of Object.values(value)) {
+      const match = extractOrcidFromUnknown(nestedValue);
+      if (match) {
+        return match;
+      }
+    }
+  }
+
+  return null;
+}
+
+export function extractOrcidFromGithubProfile(userProfile, socialAccounts = []) {
+  return extractOrcidFromUnknown(socialAccounts)
+    ?? extractOrcidFromUnknown(userProfile);
+}
+
+export function extractOrcidFromGithubHtml(html) {
+  return extractOrcidFromText(String(html ?? '').replace(/&amp;/g, '&'));
+}
+
+export function toZenodoOrcid(orcid) {
+  return stripOrcidUrl(orcid);
+}
diff --git a/src/validation/validation.js b/src/validation/validation.js
index b96b60d..ca2ecd2 100644
--- a/src/validation/validation.js
+++ b/src/validation/validation.js
@@ -1,6 +1,44 @@
 import { normalizeMetadata } from '../metadata/normalizeMetadata.js';
+import { isValidOrcidFormat } from '../utils/orcid.js';
 import { normalizeOrcid } from '../utils/orcid.js';
 
+function isValidIsoDate(value) {
+  const text = String(value ?? '').trim();
+  if (!text) {
+    return true;
+  }
+
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(text)) {
+    return false;
+  }
+
+  const [yearText, monthText, dayText] = text.split('-');
+  const year = Number(yearText);
+  const month = Number(monthText);
+  const day = Number(dayText);
+
+  if (!Number.isInteger(year) || !Number.isInteger(month) || !Number.isInteger(day)) {
+    return false;
+  }
+
+  const date = new Date(Date.UTC(year, month - 1, day));
+
+  return date.getUTCFullYear() === year
+    && date.getUTCMonth() === month - 1
+    && date.getUTCDate() === day;
+}
+
+function isValidSemanticVersion(value) {
+  const text = String(value ?? '').trim();
+
+  if (!text) {
+    return false;
+  }
+
+  // Accept SemVer with optional leading "v" (for GitHub tag parity), including prerelease/build metadata.
+  return /^v?(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?$/.test(text);
+}
+
 export function normalizeFormInput(form) {
   const cleanString = (value) => String(value ?? '').replace(/[ \t]+/g, ' ').trim();
 
@@ -31,7 +69,9 @@ export function normalizeFormInput(form) {
 export function validateMetadata(form, typeOptions) {
   const metadata = normalizeMetadata(form);
   const errors = {};
+  const authorOrcidErrors = {};
   const grantPattern = /^[A-Za-z0-9.-]+::[A-Za-z0-9.-]+$/;
+  const duplicateAuthorRows = new Set();
 
   if (!form.title) {
     errors.title = 'Title is required';
@@ -45,10 +85,66 @@ export function validateMetadata(form, typeOptions) {
     errors.license = 'License is required';
   }
 
+  if (!form.version) {
+    errors.version = 'Version is required';
+  } else if (!isValidSemanticVersion(form.version)) {
+    errors.version = 'Version must use Semantic Versioning (for example: 1.2.3 or v1.2.3).';
+  }
+
   if (!typeOptions.some((option) => option.value === form.typeOfWork)) {
     errors.typeOfWork = 'Type of work is invalid';
   }
 
+  if (!form.publicationDate) {
+    errors.publicationDate = 'Publication date is required';
+  } else if (!isValidIsoDate(form.publicationDate)) {
+    errors.publicationDate = 'Publication date must be a real date in YYYY-MM-DD format';
+  }
+
+  const authors = Array.isArray(form.authors) ? form.authors : [];
+  const seenOrcidRows = new Map();
+  const seenNameRows = new Map();
+
+  authors.forEach((author, index) => {
+    const orcidKey = String(author?.orcid ?? '').trim().toLowerCase();
+    const givenName = String(author?.givenNames ?? '').trim().toLowerCase();
+    const familyName = String(author?.familyNames ?? '').trim().toLowerCase();
+    const nameKey = givenName && familyName ? `${givenName}|${familyName}` : '';
+
+    if (orcidKey) {
+      const firstRow = seenOrcidRows.get(orcidKey);
+      if (firstRow !== undefined) {
+        duplicateAuthorRows.add(firstRow + 1);
+        duplicateAuthorRows.add(index + 1);
+      } else {
+        seenOrcidRows.set(orcidKey, index);
+      }
+    }
+
+    if (nameKey) {
+      const firstRow = seenNameRows.get(nameKey);
+      if (firstRow !== undefined) {
+        duplicateAuthorRows.add(firstRow + 1);
+        duplicateAuthorRows.add(index + 1);
+      } else {
+        seenNameRows.set(nameKey, index);
+      }
+    }
+
+    if (!isValidOrcidFormat(author?.orcid ?? '')) {
+      authorOrcidErrors[index] = 'Invalid ORCID (must be a valid 16-digit ORCID, with final checksum that can be X).';
+    }
+  });
+
+  if (duplicateAuthorRows.size > 0) {
+    const rows = [...duplicateAuthorRows].sort((a, b) => a - b);
+    errors.authors = `Duplicate author entries found on rows ${rows.join(', ')}. Remove duplicates before export.`;
+  }
+
+  if (Object.keys(authorOrcidErrors).length > 0) {
+    errors.authorOrcid = authorOrcidErrors;
+  }
+
   const grantLines = String(form.grants ?? '').split('\n');
   for (let index = 0; index < grantLines.length; index += 1) {
     const grantId = grantLines[index].trim();
diff --git a/tests/services/citationHealthScan.test.js b/tests/services/citationHealthScan.test.js
new file mode 100644
index 0000000..3424036
--- /dev/null
+++ b/tests/services/citationHealthScan.test.js
@@ -0,0 +1,424 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import { runCitationHealthScan } from '../../src/services/citationHealthScan.js';
+
+function baseContext() {
+  return {
+    warnings: [],
+    errors: [],
+    metadata: {
+      version: '1.0.0',
+      publicationDate: '2026-07-12',
+      repositoryCode: 'https://github.com/imageomics/opencite',
+      license: 'MIT',
+      authors: [
+        {
+          givenNames: 'Jane',
+          familyNames: 'Doe',
+          orcid: 'https://orcid.org/0000-0002-1825-0097',
+        },
+      ],
+      keywords: ['citation', 'metadata'],
+      abstract: 'A metadata tool.',
+      doi: '10.5281/zenodo.1234567',
+    },
+    repoData: {
+      html_url: 'https://github.com/imageomics/opencite',
+      license: { spdx_id: 'MIT' },
+    },
+    releaseData: {
+      tag_name: 'v1.0.0',
+      published_at: '2026-07-12T00:00:00Z',
+    },
+    fileValidationSummary: {
+      citation: { present: true, valid: true, errors: [] },
+      zenodo: { present: true, valid: true, errors: [] },
+    },
+  };
+}
+
+test('runCitationHealthScan returns check objects in expected shape', () => {
+  const checks = runCitationHealthScan(baseContext());
+
+  assert.equal(Array.isArray(checks), true);
+  assert.equal(checks.length >= 11, true);
+
+  for (const check of checks) {
+    assert.equal(typeof check.status, 'string');
+    assert.equal(typeof check.title, 'string');
+    assert.equal(typeof check.description, 'string');
+    assert.equal(typeof check.recommendation, 'string');
+    assert.equal(['pass', 'warning', 'error'].includes(check.status), true);
+  }
+});
+
+test('runCitationHealthScan does not include deprecated aggregate release-match check', () => {
+  const checks = runCitationHealthScan(baseContext());
+  const deprecatedCheck = checks.find((check) => check.title === 'Metadata matches latest GitHub release');
+
+  assert.equal(deprecatedCheck, undefined);
+});
+
+test('runCitationHealthScan flags warning/error conditions', () => {
+  const context = baseContext();
+  context.fileValidationSummary.citation = {
+    present: true,
+    valid: false,
+    errors: ['version is required.'],
+  };
+  context.metadata.authors = [];
+  context.metadata.doi = '';
+  context.metadata.version = '0.9.0';
+  context.metadata.license = 'Apache-2.0';
+  context.warnings = [
+    {
+      code: 'version-mismatch',
+      source: 'citation',
+      message: 'Version mismatch',
+    },
+    {
+      code: 'license-mismatch',
+      source: 'citation',
+      message: 'License mismatch',
+    },
+  ];
+
+  const checks = runCitationHealthScan(context);
+
+  const citationCheck = checks.find((check) => check.title === 'Repository has a CITATION.cff');
+  const versionCheck = checks.find((check) => check.title === 'Version is ahead of latest release tag');
+  const licenseCheck = checks.find((check) => check.title === 'License matches repository license');
+  const authorsCheck = checks.find((check) => check.title === 'Authors are present');
+  const doiCheck = checks.find((check) => check.title === 'Project DOI is available');
+
+  assert.equal(citationCheck?.status, 'error');
+  assert.equal(versionCheck?.status, 'warning');
+  assert.equal(licenseCheck?.status, 'warning');
+  assert.equal(authorsCheck?.status, 'error');
+  assert.equal(doiCheck?.status, 'pass');
+});
+
+test('version check warns when metadata version is not ahead of latest release tag', () => {
+  const context = baseContext();
+  context.metadata.version = '1.0.0';
+  context.releaseData.tag_name = 'v1.0.0';
+  context.warnings = [
+    {
+      code: 'cross-file-version-mismatch',
+      source: 'citation',
+      message: 'CITATION.cff and .zenodo.json versions differ.',
+    },
+  ];
+
+  const checks = runCitationHealthScan(context);
+  const versionCheck = checks.find((check) => check.title === 'Version is ahead of latest release tag');
+
+  assert.equal(versionCheck?.status, 'warning');
+});
+
+test('version check passes when metadata version is ahead of latest release from 0.1.0 to 1.0.0', () => {
+  const context = baseContext();
+  context.releaseData.tag_name = 'v0.1.0';
+  context.metadata.version = '1.0.0';
+
+  const checks = runCitationHealthScan(context);
+  const versionCheck = checks.find((check) => check.title === 'Version is ahead of latest release tag');
+
+  assert.equal(versionCheck?.status, 'pass');
+});
+
+test('version check passes when metadata version is ahead of latest release from 1.0.1 to 1.1.0', () => {
+  const context = baseContext();
+  context.releaseData.tag_name = 'v1.0.1';
+  context.metadata.version = '1.1.0';
+
+  const checks = runCitationHealthScan(context);
+  const versionCheck = checks.find((check) => check.title === 'Version is ahead of latest release tag');
+
+  assert.equal(versionCheck?.status, 'pass');
+});
+
+test('version check accepts v-prefixed semver with build metadata', () => {
+  const context = baseContext();
+  context.releaseData.tag_name = 'v1.2.2';
+  context.metadata.version = 'v1.2.3+build.5';
+
+  const checks = runCitationHealthScan(context);
+  const versionCheck = checks.find((check) => check.title === 'Version is ahead of latest release tag');
+
+  assert.equal(versionCheck?.status, 'pass');
+});
+
+test('version check warns when metadata version is invalid semver', () => {
+  const context = baseContext();
+  context.releaseData.tag_name = 'v1.0.1';
+  context.metadata.version = '1.1';
+
+  const checks = runCitationHealthScan(context);
+  const versionCheck = checks.find((check) => check.title === 'Version is ahead of latest release tag');
+
+  assert.equal(versionCheck?.status, 'warning');
+  assert.match(versionCheck?.description ?? '', /not parseable as semantic versioning/i);
+});
+
+test('version check rejects malformed separators in semantic version', () => {
+  const context = baseContext();
+  context.releaseData.tag_name = 'v1.0.1';
+  context.metadata.version = '1x2x3';
+
+  const checks = runCitationHealthScan(context);
+  const versionCheck = checks.find((check) => check.title === 'Version is ahead of latest release tag');
+
+  assert.equal(versionCheck?.status, 'warning');
+  assert.match(versionCheck?.description ?? '', /not parseable as semantic versioning/i);
+});
+
+test('version check warns when metadata version is older than latest release', () => {
+  const context = baseContext();
+  context.releaseData.tag_name = 'v1.0.1';
+  context.metadata.version = '1.0.0';
+
+  const checks = runCitationHealthScan(context);
+  const versionCheck = checks.find((check) => check.title === 'Version is ahead of latest release tag');
+
+  assert.equal(versionCheck?.status, 'warning');
+});
+
+test('version check passes when no existing release tag is available and metadata version is present', () => {
+  const context = baseContext();
+  context.releaseData.tag_name = '';
+
+  const checks = runCitationHealthScan(context);
+  const versionCheck = checks.find((check) => check.title === 'Version is ahead of latest release tag');
+
+  assert.equal(versionCheck?.status, 'pass');
+  assert.match(versionCheck?.description ?? '', /no baseline to compare/i);
+});
+
+test('release date check passes when metadata publication date is later than latest release date', () => {
+  const context = baseContext();
+  context.releaseData.published_at = '2026-01-01T00:00:00Z';
+  context.metadata.publicationDate = '2026-02-15';
+
+  const checks = runCitationHealthScan(context);
+  const releaseDateCheck = checks.find((check) => check.title === 'Publication date is after latest release date');
+
+  assert.equal(releaseDateCheck?.status, 'pass');
+});
+
+test('release date check warns when metadata publication date is the same as latest release date', () => {
+  const context = baseContext();
+  context.releaseData.published_at = '2026-07-12T00:00:00Z';
+  context.metadata.publicationDate = '2026-07-12';
+
+  const checks = runCitationHealthScan(context);
+  const releaseDateCheck = checks.find((check) => check.title === 'Publication date is after latest release date');
+
+  assert.equal(releaseDateCheck?.status, 'warning');
+});
+
+test('release date check warns when metadata publication date is earlier than latest release date', () => {
+  const context = baseContext();
+  context.releaseData.published_at = '2026-07-12T00:00:00Z';
+  context.metadata.publicationDate = '2026-06-30';
+
+  const checks = runCitationHealthScan(context);
+  const releaseDateCheck = checks.find((check) => check.title === 'Publication date is after latest release date');
+
+  assert.equal(releaseDateCheck?.status, 'warning');
+});
+
+test('release date check passes when no existing release publish date is available and metadata date is present', () => {
+  const context = baseContext();
+  context.releaseData.published_at = '';
+
+  const checks = runCitationHealthScan(context);
+  const releaseDateCheck = checks.find((check) => check.title === 'Publication date is after latest release date');
+
+  assert.equal(releaseDateCheck?.status, 'pass');
+  assert.match(releaseDateCheck?.description ?? '', /no baseline to compare/i);
+});
+
+test('release date check warns when metadata publication date is missing', () => {
+  const context = baseContext();
+  context.metadata.publicationDate = '';
+
+  const checks = runCitationHealthScan(context);
+  const releaseDateCheck = checks.find((check) => check.title === 'Publication date is after latest release date');
+
+  assert.equal(releaseDateCheck?.status, 'warning');
+  assert.equal(releaseDateCheck?.description, 'Publication date metadata is missing.');
+});
+
+test('license and repository checks warn when metadata fields are missing even if repository data exists', () => {
+  const context = baseContext();
+  context.metadata.license = '';
+  context.metadata.repositoryCode = '';
+
+  const checks = runCitationHealthScan(context);
+  const licenseCheck = checks.find((check) => check.title === 'License matches repository license');
+  const repositoryCheck = checks.find((check) => check.title === 'Repository URL is current');
+
+  assert.equal(licenseCheck?.status, 'warning');
+  assert.equal(licenseCheck?.description, 'Repository license is available, but metadata license is missing, so the match cannot be verified.');
+  assert.equal(licenseCheck?.recommendation, 'Set metadata license to match repository SPDX license so match verification can be completed.');
+  assert.equal(repositoryCheck?.status, 'warning');
+});
+
+test('repository URL check passes for equivalent GitHub URL variants', () => {
+  const context = baseContext();
+  context.repoData.html_url = 'https://github.com/Imageomics/OpenCite';
+  context.metadata.repositoryCode = 'git+https://github.com/Imageomics/OpenCite.git/';
+
+  const checks = runCitationHealthScan(context);
+  const repositoryCheck = checks.find((check) => check.title === 'Repository URL is current');
+
+  assert.equal(repositoryCheck?.status, 'pass');
+  assert.equal(repositoryCheck?.description, 'Repository URL metadata matches the current repository URL.');
+});
+
+test('license check warns that match cannot be verified when both repository and metadata license are missing', () => {
+  const context = baseContext();
+  context.repoData.license = null;
+  context.metadata.license = '';
+
+  const checks = runCitationHealthScan(context);
+  const licenseCheck = checks.find((check) => check.title === 'License matches repository license');
+
+  assert.equal(licenseCheck?.status, 'warning');
+  assert.equal(licenseCheck?.title, 'License matches repository license');
+  assert.equal(licenseCheck?.description, 'Neither repository nor metadata license information is available, so the match cannot be verified.');
+  assert.equal(licenseCheck?.recommendation, 'Set a clear SPDX license in repository metadata and citation files.');
+});
+
+test('license check warns when repository license is missing but metadata license is present', () => {
+  const context = baseContext();
+  context.repoData.license = null;
+  context.metadata.license = 'MIT';
+
+  const checks = runCitationHealthScan(context);
+  const licenseCheck = checks.find((check) => check.title === 'License matches repository license');
+
+  assert.equal(licenseCheck?.status, 'warning');
+  assert.equal(licenseCheck?.description, 'Metadata license is present, but repository SPDX license is missing, so the match cannot be verified.');
+  assert.equal(licenseCheck?.recommendation, 'Add repository SPDX license information and keep metadata aligned with repository policy.');
+});
+
+test('license check passes when repository and metadata licenses are both present and matching', () => {
+  const context = baseContext();
+  context.repoData.license = { spdx_id: 'MIT' };
+  context.metadata.license = 'mit';
+
+  const checks = runCitationHealthScan(context);
+  const licenseCheck = checks.find((check) => check.title === 'License matches repository license');
+
+  assert.equal(licenseCheck?.status, 'pass');
+  assert.equal(licenseCheck?.description, 'Metadata license aligns with repository license information.');
+});
+
+test('license check warns when repository and metadata licenses are both present but mismatched', () => {
+  const context = baseContext();
+  context.repoData.license = { spdx_id: 'MIT' };
+  context.metadata.license = 'Apache-2.0';
+
+  const checks = runCitationHealthScan(context);
+  const licenseCheck = checks.find((check) => check.title === 'License matches repository license');
+
+  assert.equal(licenseCheck?.status, 'warning');
+  assert.equal(licenseCheck?.description, 'Metadata license does not align with repository SPDX license.');
+});
+
+test('ORCID check reports invalid ORCID as error even when other authors are missing ORCID', () => {
+  const context = baseContext();
+  context.metadata.authors = [
+    {
+      givenNames: 'Jane',
+      familyNames: 'Doe',
+      orcid: '0000-0000-0000-0000',
+    },
+    {
+      givenNames: 'John',
+      familyNames: 'Smith',
+      orcid: '',
+    },
+  ];
+
+  const checks = runCitationHealthScan(context);
+  const orcidCheck = checks.find((check) => check.title === 'ORCID IDs are valid');
+
+  assert.equal(orcidCheck?.status, 'error');
+  assert.match(orcidCheck?.description ?? '', /invalid/i);
+});
+
+test('DOI check does not warn solely because a release exists when zenodo metadata is absent', () => {
+  const context = baseContext();
+  context.metadata.doi = '';
+  context.fileValidationSummary.zenodo.present = false;
+  context.releaseData = {
+    tag_name: 'v1.0.0',
+    published_at: '2026-07-12T00:00:00Z',
+  };
+
+  const checks = runCitationHealthScan(context);
+  const doiCheck = checks.find((check) => check.title === 'Project DOI is available');
+
+  assert.equal(doiCheck?.status, 'pass');
+});
+
+test('DOI check passes when DOI metadata is present', () => {
+  const context = baseContext();
+  context.metadata.doi = '10.5281/zenodo.1234567';
+
+  const checks = runCitationHealthScan(context);
+  const doiCheck = checks.find((check) => check.title === 'Project DOI is available');
+
+  assert.equal(doiCheck?.status, 'pass');
+  assert.equal(doiCheck?.description, 'Version-agnostic project DOI is present in citation metadata.');
+  assert.equal(doiCheck?.recommendation, 'Keep using the version-agnostic project DOI in citation metadata; version-specific release DOIs are handled separately by the archive/release workflow.');
+});
+
+test('DOI check does not warn solely because .zenodo.json is present when DOI is missing', () => {
+  const context = baseContext();
+  context.metadata.doi = '';
+  context.fileValidationSummary.zenodo.present = true;
+
+  const checks = runCitationHealthScan(context);
+  const doiCheck = checks.find((check) => check.title === 'Project DOI is available');
+
+  assert.equal(doiCheck?.status, 'pass');
+});
+
+test('DOI check does not warn when DOI is missing and no established expectation signal exists', () => {
+  const context = baseContext();
+  context.metadata.doi = '';
+
+  const checks = runCitationHealthScan(context);
+  const doiCheck = checks.find((check) => check.title === 'Project DOI is available');
+
+  assert.equal(doiCheck?.status, 'pass');
+  assert.equal(doiCheck?.description, 'A DOI is not required for this citation workflow.');
+  assert.equal(doiCheck?.recommendation, 'If a project DOI is available, include the version-agnostic project DOI in citation metadata; do not require a version-specific release DOI in CITATION.cff.');
+});
+
+test('citation file check reports missing CITATION.cff with consistent title and description', () => {
+  const context = baseContext();
+  context.fileValidationSummary.citation.present = false;
+
+  const checks = runCitationHealthScan(context);
+  const citationCheck = checks.find((check) => check.description === 'No CITATION.cff file was found in the repository.');
+
+  assert.equal(citationCheck?.status, 'warning');
+  assert.equal(citationCheck?.title, 'Repository is missing a CITATION.cff');
+});
+
+test('zenodo file check reports missing .zenodo.json with consistent title and description', () => {
+  const context = baseContext();
+  context.fileValidationSummary.zenodo.present = false;
+
+  const checks = runCitationHealthScan(context);
+  const zenodoCheck = checks.find((check) => check.description === 'No .zenodo.json file was found in the repository.');
+
+  assert.equal(zenodoCheck?.status, 'warning');
+  assert.equal(zenodoCheck?.title, 'Repository is missing a .zenodo.json');
+});
diff --git a/tests/services/citationValidation.test.js b/tests/services/citationValidation.test.js
new file mode 100644
index 0000000..b461cb5
--- /dev/null
+++ b/tests/services/citationValidation.test.js
@@ -0,0 +1,93 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import { validateCitationCffText } from '../../src/services/citationValidation.js';
+import { toCitationCff } from '../../src/services/citation.js';
+
+test('validateCitationCffText accepts valid citation metadata', () => {
+  const result = validateCitationCffText(`cff-version: 1.2.0
+title: "OpenCite"
+version: "1.2.3"
+date-released: "2026-07-12"
+repository-code: "https://github.com/Imageomics/OpenCite"
+authors:
+  - family-names: "Doe"
+    given-names: "Jane"
+`);
+
+  assert.equal(result.isValid, true);
+  assert.equal(result.errors.length, 0);
+});
+
+test('validateCitationCffText accepts unquoted scalar values for common fields', () => {
+  const result = validateCitationCffText(`cff-version: 1.2.0
+title: OpenCite
+version: 1.0.0
+date-released: 2026-07-12
+repository-code: https://github.com/Imageomics/OpenCite
+authors:
+  - family-names: Doe
+    given-names: Jane
+`);
+
+  assert.equal(result.isValid, true);
+  assert.equal(result.errors.length, 0);
+  assert.equal(result.fields.title, 'OpenCite');
+  assert.equal(result.fields.version, '1.0.0');
+  assert.equal(result.fields.repositoryCode, 'https://github.com/Imageomics/OpenCite');
+});
+
+test('validateCitationCffText rejects invalid date', () => {
+  const result = validateCitationCffText(`cff-version: 1.2.0
+title: "OpenCite"
+version: "1.2.3"
+date-released: "2026-99-12"
+repository-code: "https://github.com/Imageomics/OpenCite"
+authors:
+  - family-names: "Doe"
+    given-names: "Jane"
+`);
+
+  assert.equal(result.isValid, false);
+  assert.equal(result.errors.some((entry) => /date-released/.test(entry)), true);
+});
+
+test('validateCitationCffText rejects missing authors', () => {
+  const result = validateCitationCffText(`cff-version: 1.2.0
+title: "OpenCite"
+version: "1.2.3"
+date-released: "2026-07-12"
+repository-code: "https://github.com/Imageomics/OpenCite"
+`);
+
+  assert.equal(result.isValid, false);
+  assert.equal(result.errors.some((entry) => /authors/i.test(entry)), true);
+});
+
+test('toCitationCff omits empty author name fields in references', () => {
+  const output = toCitationCff({
+    title: 'OpenCite',
+    authors: [],
+    keywords: [],
+    license: 'MIT',
+    typeOfWork: 'software',
+    customTypeOfWork: '',
+    version: '1.0.0',
+    publicationDate: '2026-07-12',
+    repositoryCode: 'https://github.com/Imageomics/OpenCite',
+    doi: '',
+    abstract: '',
+    references: [
+      {
+        title: 'Referenced software',
+        authors: [{ orcid: 'https://orcid.org/0000-0002-1825-0097' }],
+      },
+    ],
+    grants: [],
+  });
+
+  assert.match(output, /authors:/);
+  assert.doesNotMatch(output, /family-names: ""/);
+  assert.doesNotMatch(output, /given-names: ""/);
+  assert.match(output, /orcid: "https:\/\/orcid\.org\/0000-0002-1825-0097"/);
+});
diff --git a/tests/services/githubImporter.test.js b/tests/services/githubImporter.test.js
new file mode 100644
index 0000000..cac8f04
--- /dev/null
+++ b/tests/services/githubImporter.test.js
@@ -0,0 +1,1005 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import {
+  addCitationConsistencyWarnings,
+  importGithubMetadata,
+  parseCitationCff,
+  parseZenodoJson,
+  resolvePreferredCitationPath,
+  summarizeImportedMetadataFiles,
+  validateImportedMetadataFiles,
+} from '../../src/services/githubImporter.js';
+
+test('parseCitationCff extracts top-level fields from common CFF content', () => {
+  const parsed = parseCitationCff(`cff-version: 1.2.0
+message: "Cite this software"
+title: "OpenCite"
+version: "1.2.3"
+date-released: "2026-07-12"
+repository-code: "https://github.com/Imageomics/OpenCite"
+license: "MIT"
+keywords:
+  - imageomics
+  - citation
+authors:
+  - family-names: "Doe"
+    given-names: "Jane"
+`);
+
+  assert.equal(parsed.title, 'OpenCite');
+  assert.equal(parsed.version, '1.2.3');
+  assert.equal(parsed.publicationDate, '2026-07-12');
+  assert.equal(parsed.repositoryCode, 'https://github.com/Imageomics/OpenCite');
+  assert.deepEqual(parsed.keywords, ['imageomics', 'citation']);
+  assert.equal(parsed.authors.length, 1);
+});
+
+test('parseCitationCff emits warning for preferred-citation sections', () => {
+  const parsed = parseCitationCff(`cff-version: 1.2.0
+title: "OpenCite"
+preferred-citation:
+  type: article
+  title: "Preferred paper"
+`);
+
+  assert.ok(Array.isArray(parsed._warnings));
+  assert.equal(parsed._warnings.length > 0, true);
+  assert.match(parsed._warnings[0], /preferred-citation/i);
+});
+
+test('parseCitationCff pulls authors and key metadata fields from citation content', () => {
+  const parsed = parseCitationCff(`cff-version: 1.2.0
+title: "OpenCite"
+abstract: "Citation metadata tool"
+version: "2.0.0"
+date-released: "2026-07-13"
+repository-code: "https://github.com/Imageomics/OpenCite"
+license: "MIT"
+doi: "10.5281/zenodo.1234567"
+keywords:
+  - metadata
+  - citation
+authors:
+  - name: "Jane Doe"
+    affiliation: "Imageomics Lab"
+    orcid: "https://orcid.org/0000-0002-1825-0097"
+references:
+  - doi: "10.1000/xyz123"
+  - url: "https://example.org/paper"
+`);
+
+  assert.equal(parsed.title, 'OpenCite');
+  assert.equal(parsed.abstract, 'Citation metadata tool');
+  assert.equal(parsed.version, '2.0.0');
+  assert.equal(parsed.publicationDate, '2026-07-13');
+  assert.equal(parsed.repositoryCode, 'https://github.com/Imageomics/OpenCite');
+  assert.equal(parsed.license, 'MIT');
+  assert.equal(parsed.doi, '10.5281/zenodo.1234567');
+  assert.deepEqual(parsed.keywords, ['metadata', 'citation']);
+
+  assert.equal(parsed.authors.length, 1);
+  assert.equal(parsed.authors[0].givenNames, 'Jane');
+  assert.equal(parsed.authors[0].familyNames, 'Doe');
+  assert.equal(parsed.authors[0].affiliation, 'Imageomics Lab');
+  assert.equal(parsed.authors[0].orcid, 'https://orcid.org/0000-0002-1825-0097');
+
+  assert.deepEqual(parsed.references, ['https://doi.org/10.1000/xyz123', 'https://example.org/paper']);
+});
+
+test('parseZenodoJson extracts grants and references from zenodo metadata', () => {
+  const parsed = parseZenodoJson(JSON.stringify({
+    title: 'OpenCite',
+    version: '0.1.0',
+    publication_date: '2026-07-12',
+    grants: [{ id: '021nxhr62::2118240' }],
+    references: ['https://doi.org/10.1000/xyz123'],
+    creators: [{ name: 'Doe, Jane', affiliation: 'Imageomics' }],
+  }));
+
+  assert.deepEqual(parsed.grants, ['021nxhr62::2118240']);
+  assert.deepEqual(parsed.references, ['https://doi.org/10.1000/xyz123']);
+  assert.equal(parsed.authors.length, 1);
+});
+
+test('addCitationConsistencyWarnings reports repository/version/date/license mismatches', () => {
+  const warnings = [];
+
+  addCitationConsistencyWarnings({
+    warnings,
+    citation: {
+      version: '1.0.0',
+      publicationDate: '2026-07-01',
+      repositoryCode: 'https://github.com/Imageomics/OldRepo',
+      license: 'Apache-2.0',
+    },
+    zenodo: {
+      version: '0.9.0',
+      publicationDate: '2026-07-02',
+      license: 'GPL-3.0',
+    },
+    releaseData: {
+      tag_name: 'v1.1.0',
+      published_at: '2026-07-03T00:00:00Z',
+    },
+    repoData: {
+      html_url: 'https://github.com/Imageomics/OpenCite',
+      license: { spdx_id: 'MIT' },
+    },
+    metadata: {
+      version: '1.1.0',
+    },
+  });
+
+  const codes = new Set(warnings.map((warning) => warning.code));
+
+  assert.equal(codes.has('repository-url-mismatch'), true);
+  assert.equal(codes.has('version-mismatch'), true);
+  assert.equal(codes.has('cross-file-version-mismatch'), true);
+  assert.equal(codes.has('date-mismatch'), true);
+  assert.equal(codes.has('license-mismatch'), true);
+});
+
+test('addCitationConsistencyWarnings treats v-prefixed versions and normalized repository URLs as equivalent', () => {
+  const warnings = [];
+
+  addCitationConsistencyWarnings({
+    warnings,
+    citation: {
+      version: '1.2.3',
+      repositoryCode: 'git+https://github.com/Imageomics/OpenCite.git',
+      publicationDate: '2026-07-12',
+      license: 'MIT',
+    },
+    zenodo: {
+      version: '1.2.3',
+      publicationDate: '2026-07-12',
+      license: 'mit',
+    },
+    releaseData: {
+      tag_name: 'v1.2.3',
+      published_at: '2026-07-12T13:00:00Z',
+    },
+    repoData: {
+      html_url: 'https://github.com/imageomics/OpenCite/',
+      license: { spdx_id: 'MIT' },
+    },
+    metadata: {
+      version: '1.2.3',
+    },
+  });
+
+  const mismatchCodes = new Set(
+    warnings
+      .map((warning) => warning.code)
+      .filter((code) =>
+        ['version-mismatch', 'cross-file-version-mismatch', 'repository-url-mismatch', 'date-mismatch', 'license-mismatch'].includes(code),
+      ),
+  );
+
+  assert.deepEqual([...mismatchCodes], []);
+});
+
+test('validateImportedMetadataFiles flags invalid CITATION.cff and .zenodo.json content', () => {
+  const warnings = validateImportedMetadataFiles({
+    'CITATION.cff': `cff-version: 1.2.0
+title: "OpenCite"
+version: "1.0.0"
+date-released: "2026-99-99"
+`,
+    '.zenodo.json': JSON.stringify({
+      title: 'OpenCite',
+      version: '',
+      publication_date: '2026-13-01',
+      upload_type: 'software',
+      creators: [],
+      grants: [{ id: 'invalid' }],
+    }),
+  });
+
+  const codes = new Set(warnings.map((warning) => warning.code));
+  assert.equal(codes.has('citation-file-invalid'), true);
+  assert.equal(codes.has('zenodo-file-invalid'), true);
+});
+
+test('validateImportedMetadataFiles does not emit invalid-file warnings for valid metadata files', () => {
+  const warnings = validateImportedMetadataFiles({
+    'CITATION.cff': `cff-version: 1.2.0
+title: "OpenCite"
+version: "1.0.0"
+date-released: "2026-07-12"
+repository-code: "https://github.com/imageomics/opencite"
+authors:
+  - family-names: "Doe"
+    given-names: "Jane"
+`,
+    '.zenodo.json': JSON.stringify({
+      title: 'OpenCite',
+      version: '1.0.0',
+      publication_date: '2026-07-12',
+      upload_type: 'software',
+      creators: [{ name: 'Doe, Jane' }],
+      grants: [{ id: '021nxhr62::2118240' }],
+    }),
+  });
+
+  const invalidCodes = warnings
+    .map((warning) => warning.code)
+    .filter((code) => code === 'citation-file-invalid' || code === 'zenodo-file-invalid');
+
+  assert.deepEqual(invalidCodes, []);
+});
+
+test('summarizeImportedMetadataFiles marks invalid citation file as not valid', () => {
+  const summary = summarizeImportedMetadataFiles({
+    'CITATION.cff': `cff-version: 1.2.0
+title: "OpenCite"
+version: ""
+date-released: "2026-07-12"
+`,
+  });
+
+  assert.equal(summary.citation.present, true);
+  assert.equal(summary.citation.valid, false);
+  assert.equal(summary.citation.path, 'CITATION.cff');
+  assert.equal(summary.warnings.some((warning) => warning.code === 'citation-file-invalid'), true);
+});
+
+test('summarizeImportedMetadataFiles marks valid citation file as valid', () => {
+  const summary = summarizeImportedMetadataFiles({
+    'CITATION.cff': `cff-version: 1.2.0
+title: "OpenCite"
+version: "1.0.0"
+date-released: "2026-07-12"
+repository-code: "https://github.com/imageomics/opencite"
+authors:
+  - family-names: "Doe"
+    given-names: "Jane"
+`,
+  });
+
+  assert.equal(summary.citation.present, true);
+  assert.equal(summary.citation.valid, true);
+  assert.deepEqual(summary.citation.errors, []);
+});
+
+test('resolvePreferredCitationPath only recognizes canonical CITATION.cff', () => {
+  const path = resolvePreferredCitationPath({
+    'CITATION.cff': 'title: "Upper"',
+    'citation.cff': 'title: "Lower"',
+  });
+
+  assert.equal(path, 'CITATION.cff');
+
+  const lowercaseOnly = resolvePreferredCitationPath({
+    'citation.cff': 'title: "Lower"',
+  });
+
+  assert.equal(lowercaseOnly, '');
+});
+
+test('summarizeImportedMetadataFiles ignores lowercase citation.cff files entirely', () => {
+  const summary = summarizeImportedMetadataFiles({
+    'CITATION.cff': `cff-version: 1.2.0
+title: "Upper"
+version: "1.0.0"
+date-released: "2026-07-12"
+repository-code: "https://github.com/imageomics/opencite"
+`,
+    'citation.cff': `cff-version: 1.2.0
+title: "Lower"
+version: "0.1.0"
+date-released: "2025-01-01"
+repository-code: "https://github.com/example/old"
+`,
+  });
+
+  assert.equal(summary.citation.path, 'CITATION.cff');
+  assert.equal(summary.warnings.some((warning) => warning.code === 'multiple-citation-files'), false);
+});
+
+test('importGithubMetadata inspects repository files by default and decodes UTF-8 citation content', async () => {
+  const originalFetch = globalThis.fetch;
+  const calledUrls = [];
+
+  const citationText = `cff-version: 1.2.0\ntitle: "Café Tool"\nversion: "1.0.0"\ndate-released: "2025-01-02"\nrepository-code: "https://github.com/test-owner/test-repo"\nauthors:\n  - family-names: "Doe"\n    given-names: "Jane"\n`;
+  const citationBase64 = Buffer.from(citationText, 'utf8').toString('base64');
+
+  globalThis.fetch = async (url) => {
+    const value = String(url);
+    calledUrls.push(value);
+
+    if (value.endsWith('/repos/test-owner/test-repo')) {
+      return Response.json({
+        name: 'test-repo',
+        html_url: 'https://github.com/test-owner/test-repo',
+        default_branch: 'main',
+        topics: [],
+        license: { spdx_id: 'MIT' },
+        created_at: '2025-01-01T00:00:00Z',
+      });
+    }
+
+    if (value.endsWith('/repos/test-owner/test-repo/releases/latest')) {
+      return new Response(JSON.stringify({ message: 'Not Found' }), { status: 404, headers: { 'Content-Type': 'application/json' } });
+    }
+
+    if (value.endsWith('/repos/test-owner/test-repo/commits?per_page=1&sha=main')) {
+      return Response.json([{ commit: { committer: { date: '2025-01-02T00:00:00Z' } } }]);
+    }
+
+    if (value.endsWith('/repos/test-owner/test-repo/branches/main')) {
+      return Response.json({ name: 'main' });
+    }
+
+    if (value.includes('/repos/test-owner/test-repo/contents/CITATION.cff?ref=main')) {
+      return Response.json({ encoding: 'base64', content: citationBase64 });
+    }
+
+    if (value.includes('/repos/test-owner/test-repo/contents/')) {
+      return new Response(JSON.stringify({ message: 'Not Found' }), { status: 404, headers: { 'Content-Type': 'application/json' } });
+    }
+
+    if (value.includes('/repos/test-owner/test-repo/contributors?')) {
+      return Response.json([]);
+    }
+
+    throw new Error(`Unexpected fetch URL: ${value}`);
+  };
+
+  try {
+    const result = await importGithubMetadata('https://github.com/test-owner/test-repo');
+
+    assert.equal(result.errors.length, 0);
+    assert.equal(result.metadata.title, 'Café Tool');
+    assert.equal(result.metadata.repositoryCode, 'https://github.com/test-owner/test-repo');
+    assert.equal(calledUrls.some((value) => value.includes('/contents/CITATION.cff?ref=main')), true);
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
+test('importGithubMetadata prefers CITATION.cff version over latest release tag', async () => {
+  const originalFetch = globalThis.fetch;
+
+  const citationText = `cff-version: 1.2.0\ntitle: "OpenCite"\nversion: "2.0.0"\ndate-released: "2025-01-02"\nrepository-code: "https://github.com/test-owner/test-repo"\nauthors:\n  - family-names: "Doe"\n    given-names: "Jane"\n`;
+  const citationBase64 = Buffer.from(citationText, 'utf8').toString('base64');
+
+  globalThis.fetch = async (url) => {
+    const value = String(url);
+
+    if (value.endsWith('/repos/test-owner/test-repo')) {
+      return Response.json({
+        name: 'test-repo',
+        html_url: 'https://github.com/test-owner/test-repo',
+        default_branch: 'main',
+        topics: [],
+        license: { spdx_id: 'MIT' },
+        created_at: '2025-01-01T00:00:00Z',
+      });
+    }
+
+    if (value.endsWith('/repos/test-owner/test-repo/releases/latest')) {
+      return Response.json({
+        tag_name: 'v1.5.0',
+        published_at: '2025-01-03T00:00:00Z',
+      });
+    }
+
+    if (value.endsWith('/repos/test-owner/test-repo/branches/main')) {
+      return Response.json({ name: 'main' });
+    }
+
+    if (value.includes('/repos/test-owner/test-repo/contents/CITATION.cff?ref=main')) {
+      return Response.json({ encoding: 'base64', content: citationBase64 });
+    }
+
+    if (value.includes('/repos/test-owner/test-repo/contents/')) {
+      return new Response(JSON.stringify({ message: 'Not Found' }), { status: 404, headers: { 'Content-Type': 'application/json' } });
+    }
+
+    if (value.includes('/repos/test-owner/test-repo/contributors?')) {
+      return Response.json([]);
+    }
+
+    throw new Error(`Unexpected fetch URL: ${value}`);
+  };
+
+  try {
+    const result = await importGithubMetadata('https://github.com/test-owner/test-repo');
+
+    assert.equal(result.errors.length, 0);
+    assert.equal(result.metadata.version, '2.0.0');
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
+test('importGithubMetadata does not emit commit-based fallback warning when primary citation authors exist', async () => {
+  const originalFetch = globalThis.fetch;
+
+  const citationText = `cff-version: 1.2.0\ntitle: "OpenCite"\nversion: "1.0.0"\ndate-released: "2025-01-02"\nrepository-code: "https://github.com/test-owner/test-repo"\nauthors:\n  - family-names: "Doe"\n    given-names: "Jane"\n`;
+  const citationBase64 = Buffer.from(citationText, 'utf8').toString('base64');
+
+  globalThis.fetch = async (url) => {
+    const value = String(url);
+
+    if (value.endsWith('/repos/test-owner/test-repo')) {
+      return Response.json({
+        name: 'test-repo',
+        html_url: 'https://github.com/test-owner/test-repo',
+        default_branch: 'main',
+        topics: [],
+        license: { spdx_id: 'MIT' },
+        created_at: '2025-01-01T00:00:00Z',
+      });
+    }
+
+    if (value.endsWith('/repos/test-owner/test-repo/releases/latest')) {
+      return new Response(JSON.stringify({ message: 'Not Found' }), { status: 404, headers: { 'Content-Type': 'application/json' } });
+    }
+
+    if (value.endsWith('/repos/test-owner/test-repo/commits?per_page=1&sha=main')) {
+      return Response.json([{ commit: { committer: { date: '2025-01-02T00:00:00Z' } } }]);
+    }
+
+    if (value.endsWith('/repos/test-owner/test-repo/branches/main')) {
+      return Response.json({ name: 'main' });
+    }
+
+    if (value.includes('/repos/test-owner/test-repo/contents/CITATION.cff?ref=main')) {
+      return Response.json({ encoding: 'base64', content: citationBase64 });
+    }
+
+    if (value.includes('/repos/test-owner/test-repo/contents/')) {
+      return new Response(JSON.stringify({ message: 'Not Found' }), { status: 404, headers: { 'Content-Type': 'application/json' } });
+    }
+
+    if (value.includes('/repos/test-owner/test-repo/contributors?')) {
+      return Response.json([{ login: 'janedoe', type: 'User' }]);
+    }
+
+    if (value.endsWith('/users/janedoe')) {
+      return Response.json({
+        login: 'janedoe',
+        type: 'User',
+        name: 'Jane Doe',
+        company: 'Imageomics',
+        html_url: 'https://github.com/janedoe',
+      });
+    }
+
+    if (value.endsWith('/users/janedoe/social_accounts')) {
+      return Response.json([]);
+    }
+
+    if (value === 'https://github.com/janedoe') {
+      return new Response('<html></html>', { status: 200, headers: { 'Content-Type': 'text/html' } });
+    }
+
+    throw new Error(`Unexpected fetch URL: ${value}`);
+  };
+
+  try {
+    const result = await importGithubMetadata('https://github.com/test-owner/test-repo', {
+      contributorFallbackLimit: 5,
+    });
+
+    assert.equal(result.errors.length, 0);
+    assert.equal(result.metadata.authors.length > 0, true);
+    assert.equal(result.warnings.some((warning) => warning.code === 'commit-based-fallback'), false);
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
+test('importGithubMetadata deduplicates duplicate authors imported from CITATION.cff', async () => {
+  const originalFetch = globalThis.fetch;
+
+  const citationText = `cff-version: 1.2.0\ntitle: "OpenCite"\nversion: "1.0.0"\ndate-released: "2025-01-02"\nrepository-code: "https://github.com/test-owner/test-repo"\nauthors:\n  - family-names: "Doe"\n    given-names: "Jane"\n  - family-names: "doe"\n    given-names: "jane"\n`;
+  const citationBase64 = Buffer.from(citationText, 'utf8').toString('base64');
+
+  globalThis.fetch = async (url) => {
+    const value = String(url);
+
+    if (value.endsWith('/repos/test-owner/test-repo')) {
+      return Response.json({
+        name: 'test-repo',
+        html_url: 'https://github.com/test-owner/test-repo',
+        default_branch: 'main',
+        topics: [],
+        license: { spdx_id: 'MIT' },
+        created_at: '2025-01-01T00:00:00Z',
+      });
+    }
+
+    if (value.endsWith('/repos/test-owner/test-repo/releases/latest')) {
+      return new Response(JSON.stringify({ message: 'Not Found' }), { status: 404, headers: { 'Content-Type': 'application/json' } });
+    }
+
+    if (value.endsWith('/repos/test-owner/test-repo/commits?per_page=1&sha=main')) {
+      return Response.json([{ commit: { committer: { date: '2025-01-02T00:00:00Z' } } }]);
+    }
+
+    if (value.endsWith('/repos/test-owner/test-repo/branches/main')) {
+      return Response.json({ name: 'main' });
+    }
+
+    if (value.includes('/repos/test-owner/test-repo/contents/CITATION.cff?ref=main')) {
+      return Response.json({ encoding: 'base64', content: citationBase64 });
+    }
+
+    if (value.includes('/repos/test-owner/test-repo/contents/')) {
+      return new Response(JSON.stringify({ message: 'Not Found' }), { status: 404, headers: { 'Content-Type': 'application/json' } });
+    }
+
+    if (value.includes('/repos/test-owner/test-repo/contributors?')) {
+      return Response.json([]);
+    }
+
+    throw new Error(`Unexpected fetch URL: ${value}`);
+  };
+
+  try {
+    const result = await importGithubMetadata('https://github.com/test-owner/test-repo');
+
+    assert.equal(result.errors.length, 0);
+    assert.equal(result.metadata.authors.length, 1);
+    assert.equal(result.metadata.authors[0].givenNames, 'Jane');
+    assert.equal(result.metadata.authors[0].familyNames, 'Doe');
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
+test('importGithubMetadata preserves citation authors when CITATION.cff is invalid but parseable', async () => {
+  const originalFetch = globalThis.fetch;
+
+  const citationText = `cff-version: 1.2.0\ntitle: "OpenCite"\nversion: "1.0.0"\ndate-released: "2025-99-99"\nrepository-code: "https://github.com/test-owner/test-repo"\nauthors:\n  - family-names: "Doe"\n    given-names: "Jane"\n  - family-names: "Smith"\n    given-names: "John"\n`;
+  const citationBase64 = Buffer.from(citationText, 'utf8').toString('base64');
+
+  globalThis.fetch = async (url) => {
+    const value = String(url);
+
+    if (value.endsWith('/repos/test-owner/test-repo')) {
+      return Response.json({
+        name: 'test-repo',
+        html_url: 'https://github.com/test-owner/test-repo',
+        default_branch: 'main',
+        topics: [],
+        license: { spdx_id: 'MIT' },
+        created_at: '2025-01-01T00:00:00Z',
+      });
+    }
+
+    if (value.endsWith('/repos/test-owner/test-repo/releases/latest')) {
+      return new Response(JSON.stringify({ message: 'Not Found' }), { status: 404, headers: { 'Content-Type': 'application/json' } });
+    }
+
+    if (value.endsWith('/repos/test-owner/test-repo/commits?per_page=1&sha=main')) {
+      return Response.json([{ commit: { committer: { date: '2025-01-02T00:00:00Z' } } }]);
+    }
+
+    if (value.endsWith('/repos/test-owner/test-repo/branches/main')) {
+      return Response.json({ name: 'main' });
+    }
+
+    if (value.includes('/repos/test-owner/test-repo/contents/CITATION.cff?ref=main')) {
+      return Response.json({ encoding: 'base64', content: citationBase64 });
+    }
+
+    if (value.includes('/repos/test-owner/test-repo/contents/')) {
+      return new Response(JSON.stringify({ message: 'Not Found' }), { status: 404, headers: { 'Content-Type': 'application/json' } });
+    }
+
+    if (value.includes('/repos/test-owner/test-repo/contributors?')) {
+      return Response.json([]);
+    }
+
+    throw new Error(`Unexpected fetch URL: ${value}`);
+  };
+
+  try {
+    const result = await importGithubMetadata('https://github.com/test-owner/test-repo');
+
+    assert.equal(result.errors.length, 0);
+    assert.equal(result.warnings.some((warning) => warning.code === 'citation-file-skipped'), true);
+    assert.equal(result.metadata.authors.some((author) => author.givenNames === 'Jane' && author.familyNames === 'Doe'), true);
+    assert.equal(result.metadata.authors.some((author) => author.givenNames === 'John' && author.familyNames === 'Smith'), true);
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
+test('importGithubMetadata ignores invalid CITATION.cff non-author fields but still uses repository/release fallback metadata', async () => {
+  const originalFetch = globalThis.fetch;
+
+  const citationText = `cff-version: 1.2.0\ntitle: "Incorrect Title"\nversion: "9.9.9"\ndate-released: "2025-99-99"\nrepository-code: "https://github.com/other/repo"\nlicense: "Apache-2.0"\nauthors:\n  - family-names: "Doe"\n    given-names: "Jane"\n`;
+  const citationBase64 = Buffer.from(citationText, 'utf8').toString('base64');
+
+  globalThis.fetch = async (url) => {
+    const value = String(url);
+
+    if (value.endsWith('/repos/test-owner/test-repo')) {
+      return Response.json({
+        name: 'repo-fallback-name',
+        html_url: 'https://github.com/test-owner/test-repo',
+        default_branch: 'main',
+        topics: [],
+        license: { spdx_id: 'MIT' },
+        description: 'Repository description fallback',
+        created_at: '2025-01-01T00:00:00Z',
+      });
+    }
+
+    if (value.endsWith('/repos/test-owner/test-repo/releases/latest')) {
+      return Response.json({
+        tag_name: 'v1.5.0',
+        published_at: '2025-01-03T00:00:00Z',
+      });
+    }
+
+    if (value.endsWith('/repos/test-owner/test-repo/branches/main')) {
+      return Response.json({ name: 'main' });
+    }
+
+    if (value.includes('/repos/test-owner/test-repo/contents/CITATION.cff?ref=main')) {
+      return Response.json({ encoding: 'base64', content: citationBase64 });
+    }
+
+    if (value.includes('/repos/test-owner/test-repo/contents/')) {
+      return new Response(JSON.stringify({ message: 'Not Found' }), { status: 404, headers: { 'Content-Type': 'application/json' } });
+    }
+
+    if (value.includes('/repos/test-owner/test-repo/contributors?')) {
+      return Response.json([]);
+    }
+
+    throw new Error(`Unexpected fetch URL: ${value}`);
+  };
+
+  try {
+    const result = await importGithubMetadata('https://github.com/test-owner/test-repo');
+
+    assert.equal(result.errors.length, 0);
+    assert.equal(result.warnings.some((warning) => warning.code === 'citation-file-invalid'), true);
+    assert.equal(result.warnings.some((warning) => warning.code === 'citation-file-skipped'), true);
+    assert.equal(result.metadata.title, 'repo-fallback-name');
+    assert.equal(result.metadata.version, 'v1.5.0');
+    assert.equal(result.metadata.license, 'MIT');
+    assert.equal(result.metadata.authors.some((author) => author.givenNames === 'Jane' && author.familyNames === 'Doe'), true);
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
+test('importGithubMetadata ignores invalid .zenodo.json and still uses repository/release fallback metadata', async () => {
+  const originalFetch = globalThis.fetch;
+
+  const zenodoText = JSON.stringify({
+    title: 'Broken Zenodo Title',
+    version: '',
+    publication_date: '2025-13-40',
+    creators: [],
+    grants: [{ id: 'invalid' }],
+  });
+  const zenodoBase64 = Buffer.from(zenodoText, 'utf8').toString('base64');
+
+  globalThis.fetch = async (url) => {
+    const value = String(url);
+
+    if (value.endsWith('/repos/test-owner/test-repo')) {
+      return Response.json({
+        name: 'repo-fallback-name',
+        html_url: 'https://github.com/test-owner/test-repo',
+        default_branch: 'main',
+        topics: ['citation'],
+        license: { spdx_id: 'MIT' },
+        description: 'Repository description fallback',
+        created_at: '2025-01-01T00:00:00Z',
+      });
+    }
+
+    if (value.endsWith('/repos/test-owner/test-repo/releases/latest')) {
+      return Response.json({
+        tag_name: 'v2.1.0',
+        published_at: '2025-02-03T00:00:00Z',
+      });
+    }
+
+    if (value.endsWith('/repos/test-owner/test-repo/branches/main')) {
+      return Response.json({ name: 'main' });
+    }
+
+    if (value.includes('/repos/test-owner/test-repo/contents/.zenodo.json?ref=main')) {
+      return Response.json({ encoding: 'base64', content: zenodoBase64 });
+    }
+
+    if (value.includes('/repos/test-owner/test-repo/contents/')) {
+      return new Response(JSON.stringify({ message: 'Not Found' }), { status: 404, headers: { 'Content-Type': 'application/json' } });
+    }
+
+    if (value.includes('/repos/test-owner/test-repo/contributors?')) {
+      return Response.json([]);
+    }
+
+    throw new Error(`Unexpected fetch URL: ${value}`);
+  };
+
+  try {
+    const result = await importGithubMetadata('https://github.com/test-owner/test-repo');
+
+    assert.equal(result.errors.length, 0);
+    assert.equal(result.warnings.some((warning) => warning.code === 'zenodo-file-invalid'), true);
+    assert.equal(result.warnings.some((warning) => warning.code === 'zenodo-file-skipped'), true);
+    assert.equal(result.metadata.title, 'repo-fallback-name');
+    assert.equal(result.metadata.version, 'v2.1.0');
+    assert.equal(result.metadata.publicationDate, '2025-02-03');
+    assert.equal(result.metadata.repositoryCode, 'https://github.com/test-owner/test-repo');
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
+test('importGithubMetadata includes contributor authors in addition to citation authors', async () => {
+  const originalFetch = globalThis.fetch;
+
+  const citationText = `cff-version: 1.2.0\ntitle: "OpenCite"\nversion: "1.0.0"\ndate-released: "2025-01-02"\nrepository-code: "https://github.com/test-owner/test-repo"\nauthors:\n  - family-names: "Doe"\n    given-names: "Jane"\n`;
+  const citationBase64 = Buffer.from(citationText, 'utf8').toString('base64');
+
+  globalThis.fetch = async (url) => {
+    const value = String(url);
+
+    if (value.endsWith('/repos/test-owner/test-repo')) {
+      return Response.json({
+        name: 'test-repo',
+        html_url: 'https://github.com/test-owner/test-repo',
+        default_branch: 'main',
+        topics: [],
+        license: { spdx_id: 'MIT' },
+        created_at: '2025-01-01T00:00:00Z',
+      });
+    }
+
+    if (value.endsWith('/repos/test-owner/test-repo/releases/latest')) {
+      return new Response(JSON.stringify({ message: 'Not Found' }), { status: 404, headers: { 'Content-Type': 'application/json' } });
+    }
+
+    if (value.endsWith('/repos/test-owner/test-repo/commits?per_page=1&sha=main')) {
+      return Response.json([{ commit: { committer: { date: '2025-01-02T00:00:00Z' } } }]);
+    }
+
+    if (value.endsWith('/repos/test-owner/test-repo/branches/main')) {
+      return Response.json({ name: 'main' });
+    }
+
+    if (value.includes('/repos/test-owner/test-repo/contents/CITATION.cff?ref=main')) {
+      return Response.json({ encoding: 'base64', content: citationBase64 });
+    }
+
+    if (value.includes('/repos/test-owner/test-repo/contents/')) {
+      return new Response(JSON.stringify({ message: 'Not Found' }), { status: 404, headers: { 'Content-Type': 'application/json' } });
+    }
+
+    if (value.includes('/repos/test-owner/test-repo/contributors?')) {
+      return Response.json([
+        { login: 'janedoe', type: 'User' },
+        { login: 'johnsmith', type: 'User' },
+      ]);
+    }
+
+    if (value.endsWith('/users/janedoe')) {
+      return Response.json({
+        login: 'janedoe',
+        type: 'User',
+        name: 'Jane Doe',
+        company: 'Imageomics',
+        html_url: 'https://github.com/janedoe',
+      });
+    }
+
+    if (value.endsWith('/users/johnsmith')) {
+      return Response.json({
+        login: 'johnsmith',
+        type: 'User',
+        name: 'John Smith',
+        company: 'Imageomics',
+        html_url: 'https://github.com/johnsmith',
+      });
+    }
+
+    if (value.endsWith('/users/janedoe/social_accounts') || value.endsWith('/users/johnsmith/social_accounts')) {
+      return Response.json([]);
+    }
+
+    if (value === 'https://github.com/janedoe' || value === 'https://github.com/johnsmith') {
+      return new Response('<html></html>', { status: 200, headers: { 'Content-Type': 'text/html' } });
+    }
+
+    throw new Error(`Unexpected fetch URL: ${value}`);
+  };
+
+  try {
+    const result = await importGithubMetadata('https://github.com/test-owner/test-repo', {
+      contributorFallbackLimit: 5,
+    });
+
+    assert.equal(result.errors.length, 0);
+    assert.equal(result.metadata.authors.some((author) => author.givenNames === 'Jane' && author.familyNames === 'Doe'), true);
+    assert.equal(result.metadata.authors.some((author) => author.givenNames === 'John' && author.familyNames === 'Smith'), true);
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
+test('importGithubMetadata orders imported authors by contributor rank', async () => {
+  const originalFetch = globalThis.fetch;
+
+  const citationText = `cff-version: 1.2.0\ntitle: "OpenCite"\nversion: "1.0.0"\ndate-released: "2025-01-02"\nrepository-code: "https://github.com/test-owner/test-repo"\nauthors:\n  - family-names: "Doe"\n    given-names: "Jane"\n  - family-names: "Smith"\n    given-names: "John"\n`;
+  const citationBase64 = Buffer.from(citationText, 'utf8').toString('base64');
+
+  globalThis.fetch = async (url) => {
+    const value = String(url);
+
+    if (value.endsWith('/repos/test-owner/test-repo')) {
+      return Response.json({
+        name: 'test-repo',
+        html_url: 'https://github.com/test-owner/test-repo',
+        default_branch: 'main',
+        topics: [],
+        license: { spdx_id: 'MIT' },
+        created_at: '2025-01-01T00:00:00Z',
+      });
+    }
+
+    if (value.endsWith('/repos/test-owner/test-repo/releases/latest')) {
+      return new Response(JSON.stringify({ message: 'Not Found' }), { status: 404, headers: { 'Content-Type': 'application/json' } });
+    }
+
+    if (value.endsWith('/repos/test-owner/test-repo/commits?per_page=1&sha=main')) {
+      return Response.json([{ commit: { committer: { date: '2025-01-02T00:00:00Z' } } }]);
+    }
+
+    if (value.endsWith('/repos/test-owner/test-repo/branches/main')) {
+      return Response.json({ name: 'main' });
+    }
+
+    if (value.includes('/repos/test-owner/test-repo/contents/CITATION.cff?ref=main')) {
+      return Response.json({ encoding: 'base64', content: citationBase64 });
+    }
+
+    if (value.includes('/repos/test-owner/test-repo/contents/')) {
+      return new Response(JSON.stringify({ message: 'Not Found' }), { status: 404, headers: { 'Content-Type': 'application/json' } });
+    }
+
+    if (value.includes('/repos/test-owner/test-repo/contributors?')) {
+      // John appears first => highest contributor rank.
+      return Response.json([
+        { login: 'johnsmith', type: 'User' },
+        { login: 'janedoe', type: 'User' },
+      ]);
+    }
+
+    if (value.endsWith('/users/janedoe')) {
+      return Response.json({
+        login: 'janedoe',
+        type: 'User',
+        name: 'Jane Doe',
+        company: 'Imageomics',
+        html_url: 'https://github.com/janedoe',
+      });
+    }
+
+    if (value.endsWith('/users/johnsmith')) {
+      return Response.json({
+        login: 'johnsmith',
+        type: 'User',
+        name: 'John Smith',
+        company: 'Imageomics',
+        html_url: 'https://github.com/johnsmith',
+      });
+    }
+
+    if (value.endsWith('/users/janedoe/social_accounts') || value.endsWith('/users/johnsmith/social_accounts')) {
+      return Response.json([]);
+    }
+
+    if (value === 'https://github.com/janedoe' || value === 'https://github.com/johnsmith') {
+      return new Response('<html></html>', { status: 200, headers: { 'Content-Type': 'text/html' } });
+    }
+
+    throw new Error(`Unexpected fetch URL: ${value}`);
+  };
+
+  try {
+    const result = await importGithubMetadata('https://github.com/test-owner/test-repo', {
+      contributorFallbackLimit: 5,
+    });
+
+    assert.equal(result.errors.length, 0);
+    assert.equal(result.metadata.authors.length >= 2, true);
+    assert.equal(result.metadata.authors[0].givenNames, 'John');
+    assert.equal(result.metadata.authors[0].familyNames, 'Smith');
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
+test('importGithubMetadata deduplicates likely name variants between citation and contributors', async () => {
+  const originalFetch = globalThis.fetch;
+
+  const citationText = `cff-version: 1.2.0\ntitle: "OpenCite"\nversion: "1.0.0"\ndate-released: "2025-01-02"\nrepository-code: "https://github.com/test-owner/test-repo"\nauthors:\n  - family-names: "Doe"\n    given-names: "Jane"\n`;
+  const citationBase64 = Buffer.from(citationText, 'utf8').toString('base64');
+
+  globalThis.fetch = async (url) => {
+    const value = String(url);
+
+    if (value.endsWith('/repos/test-owner/test-repo')) {
+      return Response.json({
+        name: 'test-repo',
+        html_url: 'https://github.com/test-owner/test-repo',
+        default_branch: 'main',
+        topics: [],
+        license: { spdx_id: 'MIT' },
+        created_at: '2025-01-01T00:00:00Z',
+      });
+    }
+
+    if (value.endsWith('/repos/test-owner/test-repo/releases/latest')) {
+      return new Response(JSON.stringify({ message: 'Not Found' }), { status: 404, headers: { 'Content-Type': 'application/json' } });
+    }
+
+    if (value.endsWith('/repos/test-owner/test-repo/commits?per_page=1&sha=main')) {
+      return Response.json([{ commit: { committer: { date: '2025-01-02T00:00:00Z' } } }]);
+    }
+
+    if (value.endsWith('/repos/test-owner/test-repo/branches/main')) {
+      return Response.json({ name: 'main' });
+    }
+
+    if (value.includes('/repos/test-owner/test-repo/contents/CITATION.cff?ref=main')) {
+      return Response.json({ encoding: 'base64', content: citationBase64 });
+    }
+
+    if (value.includes('/repos/test-owner/test-repo/contents/')) {
+      return new Response(JSON.stringify({ message: 'Not Found' }), { status: 404, headers: { 'Content-Type': 'application/json' } });
+    }
+
+    if (value.includes('/repos/test-owner/test-repo/contributors?')) {
+      return Response.json([{ login: 'janedoe', type: 'User' }]);
+    }
+
+    if (value.endsWith('/users/janedoe')) {
+      return Response.json({
+        login: 'janedoe',
+        type: 'User',
+        name: 'Jane A Doe',
+        company: 'Imageomics',
+        html_url: 'https://github.com/janedoe',
+      });
+    }
+
+    if (value.endsWith('/users/janedoe/social_accounts')) {
+      return Response.json([]);
+    }
+
+    if (value === 'https://github.com/janedoe') {
+      return new Response('<html></html>', { status: 200, headers: { 'Content-Type': 'text/html' } });
+    }
+
+    throw new Error(`Unexpected fetch URL: ${value}`);
+  };
+
+  try {
+    const result = await importGithubMetadata('https://github.com/test-owner/test-repo', {
+      contributorFallbackLimit: 5,
+    });
+
+    assert.equal(result.errors.length, 0);
+    assert.equal(result.metadata.authors.length, 1);
+    assert.equal(result.metadata.authors[0].familyNames, 'Doe');
+    assert.equal(result.metadata.authors[0].givenNames.startsWith('Jane'), true);
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
diff --git a/tests/services/metadataComparison.test.js b/tests/services/metadataComparison.test.js
new file mode 100644
index 0000000..a68e467
--- /dev/null
+++ b/tests/services/metadataComparison.test.js
@@ -0,0 +1,83 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import { compareExistingMetadataFiles } from '../../src/services/metadataComparison.js';
+
+function baseContext() {
+  return {
+    repoData: {
+      html_url: 'https://github.com/imageomics/opencite',
+      license: { spdx_id: 'GPL-3.0' },
+      topics: ['citation', 'metadata'],
+      description: 'OpenCite repository',
+    },
+    releaseData: {
+      tag_name: 'v1.2.1',
+      published_at: '2026-07-13T00:00:00Z',
+    },
+    contributorLookupAuthors: [
+      { givenNames: 'Jane', familyNames: 'Doe' },
+    ],
+    fileValidationSummary: {
+      citation: { present: true },
+      zenodo: { present: false },
+    },
+    citationForComparison: {
+      version: '1.0.0',
+      repositoryCode: 'https://github.com/imageomics/old-name',
+      publicationDate: '2026-07-01',
+      license: 'MIT',
+      authors: [{ name: 'Jane Doe' }],
+      keywords: ['citation'],
+      abstract: '',
+      doi: '',
+    },
+    zenodoForComparison: null,
+  };
+}
+
+test('compareExistingMetadataFiles returns expected statuses and recommendations', () => {
+  const comparisons = compareExistingMetadataFiles(baseContext());
+
+  const byField = new Map(comparisons.map((item) => [item.field, item]));
+
+  assert.equal(byField.get('version')?.status, 'different');
+  assert.equal(byField.get('version')?.recommendation, 'Update version to latest release.');
+
+  assert.equal(byField.get('repository-code')?.status, 'different');
+  assert.equal(byField.get('repository-code')?.recommendation, 'Repository was renamed. Update repository-code.');
+
+  assert.equal(byField.get('license')?.status, 'different');
+  assert.equal(byField.get('license')?.recommendation, 'Review repository license and align citation metadata if needed.');
+
+  assert.equal(byField.get('abstract')?.status, 'missing');
+  assert.equal(byField.get('doi')?.status, 'cannot determine');
+});
+
+test('compareExistingMetadataFiles marks identical fields correctly', () => {
+  const context = baseContext();
+  context.citationForComparison = {
+    version: '1.2.1',
+    repositoryCode: 'https://github.com/imageomics/opencite',
+    publicationDate: '2026-07-13',
+    license: 'GPL-3.0',
+    authors: [{ givenNames: 'Jane', familyNames: 'Doe' }],
+    keywords: ['citation', 'metadata'],
+    abstract: 'OpenCite repository',
+    doi: '10.0000/example',
+  };
+
+  const comparisons = compareExistingMetadataFiles(context);
+  const deterministicFields = new Set([
+    'version',
+    'repository-code',
+    'date-released',
+    'license',
+    'authors',
+    'keywords',
+    'abstract',
+  ]);
+  const comparable = comparisons.filter((item) => deterministicFields.has(item.field));
+
+  assert.equal(comparable.every((item) => item.status === 'identical'), true);
+});
diff --git a/tests/services/metadataFixtures.test.js b/tests/services/metadataFixtures.test.js
new file mode 100644
index 0000000..dab137f
--- /dev/null
+++ b/tests/services/metadataFixtures.test.js
@@ -0,0 +1,58 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { readFile } from 'node:fs/promises';
+
+import { validateCitationCffText } from '../../src/services/citationValidation.js';
+import { validateZenodoJsonText } from '../../src/services/zenodoValidation.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+async function readFixture(name) {
+  const filePath = path.join(__dirname, '../../src/services/fixtures', name);
+  return readFile(filePath, 'utf8');
+}
+
+test('valid citation fixture passes validation', async () => {
+  const text = await readFixture('valid.CITATION.cff');
+  const result = validateCitationCffText(text);
+
+  assert.equal(result.isValid, true);
+  assert.equal(result.errors.length, 0);
+  assert.match(result.report, /Status: PASS/);
+});
+
+test('invalid citation fixture fails validation with useful report details', async () => {
+  const text = await readFixture('invalid.CITATION.cff');
+  const result = validateCitationCffText(text);
+
+  assert.equal(result.isValid, false);
+  assert.equal(result.errors.some((entry) => /date-released/.test(entry)), true);
+  assert.match(result.report, /Status: FAIL/);
+  assert.match(result.report, /date-released/);
+});
+
+test('valid zenodo fixture passes validation', async () => {
+  const text = await readFixture('valid.zenodo.json');
+  const result = validateZenodoJsonText(text);
+
+  assert.equal(result.isValid, true);
+  assert.equal(result.errors.length, 0);
+  assert.match(result.report, /Status: PASS/);
+});
+
+test('invalid zenodo fixture fails validation with useful report details', async () => {
+  const text = await readFixture('invalid.zenodo.json');
+  const result = validateZenodoJsonText(text);
+
+  assert.equal(result.isValid, false);
+  assert.equal(result.errors.some((entry) => /title is required/.test(entry)), true);
+  assert.equal(result.errors.some((entry) => /version is required/.test(entry)), true);
+  assert.equal(result.errors.some((entry) => /publication_date/.test(entry)), true);
+  assert.equal(result.errors.some((entry) => /creators/.test(entry)), true);
+  assert.equal(result.errors.some((entry) => /grants\[0\]/.test(entry)), true);
+  assert.match(result.report, /Status: FAIL/);
+  assert.match(result.report, /Errors:/);
+});
diff --git a/tests/services/metadataReview.test.js b/tests/services/metadataReview.test.js
new file mode 100644
index 0000000..675e11d
--- /dev/null
+++ b/tests/services/metadataReview.test.js
@@ -0,0 +1,68 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import { runMetadataReviewPipeline } from '../../src/services/metadataReview.js';
+
+test('runMetadataReviewPipeline recommends keep when files are valid and no consistency issues', () => {
+  const review = runMetadataReviewPipeline({
+    warnings: [],
+    fileValidationSummary: {
+      citation: { present: true, valid: true, path: 'CITATION.cff', errors: [] },
+      zenodo: { present: true, valid: true, path: '.zenodo.json', errors: [] },
+    },
+  });
+
+  assert.equal(review.summary.byStatus.correct >= 2, true);
+  assert.equal(review.recommendations.canKeepCurrentFiles, true);
+  assert.equal(review.recommendations.canUpdateSpecificFields, false);
+});
+
+test('runMetadataReviewPipeline recommends regenerate for invalid citation file', () => {
+  const review = runMetadataReviewPipeline({
+    warnings: [],
+    fileValidationSummary: {
+      citation: {
+        present: true,
+        valid: false,
+        path: 'CITATION.cff',
+        errors: ['version is required.'],
+      },
+      zenodo: { present: true, valid: true, path: '.zenodo.json', errors: [] },
+    },
+  });
+
+  assert.equal(review.recommendations.shouldGenerateNewFiles, true);
+  assert.equal(review.recommendations.citationNeedsRegenerate, true);
+  assert.equal(
+    review.findings.some((finding) => finding.status === 'invalid' && finding.file === 'CITATION.cff'),
+    true,
+  );
+});
+
+test('runMetadataReviewPipeline recommends update fields for consistency mismatches', () => {
+  const review = runMetadataReviewPipeline({
+    warnings: [
+      {
+        code: 'version-mismatch',
+        source: 'citation',
+        message: 'CITATION.cff version differs from latest release tag.',
+      },
+      {
+        code: 'repository-url-mismatch',
+        source: 'citation',
+        message: 'CITATION.cff repository-code differs from repository URL.',
+      },
+    ],
+    fileValidationSummary: {
+      citation: { present: true, valid: true, path: 'CITATION.cff', errors: [] },
+      zenodo: { present: true, valid: true, path: '.zenodo.json', errors: [] },
+    },
+  });
+
+  assert.equal(review.recommendations.canKeepCurrentFiles, false);
+  assert.equal(review.recommendations.canUpdateSpecificFields, true);
+  assert.equal(
+    review.findings.some((finding) => finding.status === 'outdated' && finding.action === 'update-field'),
+    true,
+  );
+});
diff --git a/tests/services/metadataValidators.test.js b/tests/services/metadataValidators.test.js
new file mode 100644
index 0000000..6f5ff83
--- /dev/null
+++ b/tests/services/metadataValidators.test.js
@@ -0,0 +1,112 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import {
+  runMetadataValidators,
+  validateAbstract,
+  validateAuthors,
+  validateDOI,
+  validateKeywords,
+  validateLicense,
+  validateORCID,
+  validateReleaseDate,
+  validateRepositoryUrl,
+  validateVersion,
+} from '../../src/services/metadataValidators.js';
+
+function buildContext() {
+  return {
+    repoData: {
+      html_url: 'https://github.com/imageomics/opencite',
+      license: { spdx_id: 'MIT' },
+      topics: ['citation', 'metadata'],
+      description: 'OpenCite metadata tool',
+    },
+    releaseData: {
+      tag_name: 'v1.2.3',
+      published_at: '2026-07-13T00:00:00Z',
+    },
+    contributorLookupAuthors: [
+      { givenNames: 'Jane', familyNames: 'Doe' },
+    ],
+  };
+}
+
+test('individual validators return standardized ValidationResult shape', () => {
+  const context = buildContext();
+  const metadata = {
+    version: '1.2.3',
+    repositoryCode: 'https://github.com/imageomics/opencite',
+    license: 'MIT',
+    publicationDate: '2026-07-13',
+    authors: [{ givenNames: 'Jane', familyNames: 'Doe', orcid: '' }],
+    doi: '',
+    keywords: ['citation', 'metadata'],
+    abstract: 'OpenCite metadata tool',
+  };
+
+  const validators = [
+    validateVersion,
+    validateRepositoryUrl,
+    validateLicense,
+    validateReleaseDate,
+    validateAuthors,
+    validateORCID,
+    validateDOI,
+    validateKeywords,
+    validateAbstract,
+  ];
+
+  for (const validator of validators) {
+    const result = validator({ file: 'CITATION.cff', metadata, context });
+    assert.equal(typeof result.file, 'string');
+    assert.equal(typeof result.field, 'string');
+    assert.equal(typeof result.status, 'string');
+    assert.equal(typeof result.currentValue, 'string');
+    assert.equal(typeof result.githubValue, 'string');
+    assert.equal(typeof result.recommendation, 'string');
+    assert.equal(['identical', 'different', 'missing', 'cannot determine'].includes(result.status), true);
+  }
+});
+
+test('runMetadataValidators executes default registry and is easy to extend', () => {
+  const context = buildContext();
+  const metadata = {
+    version: '0.1.0',
+    repositoryCode: 'https://github.com/imageomics/old',
+    license: 'GPL-3.0',
+    publicationDate: '2025-01-01',
+    authors: [],
+    doi: '',
+    keywords: [],
+    abstract: '',
+  };
+
+  const results = runMetadataValidators({ file: 'CITATION.cff', metadata, context });
+  assert.equal(results.length >= 9, true);
+
+  const custom = runMetadataValidators({
+    file: 'CITATION.cff',
+    metadata,
+    context,
+    validators: [
+      () => ({
+        file: 'CITATION.cff',
+        field: 'custom',
+        status: 'cannot determine',
+        currentValue: '',
+        githubValue: '',
+        recommendation: 'Custom validator works.',
+      }),
+    ],
+  });
+
+  assert.deepEqual(custom, [{
+    file: 'CITATION.cff',
+    field: 'custom',
+    status: 'cannot determine',
+    currentValue: '',
+    githubValue: '',
+    recommendation: 'Custom validator works.',
+  }]);
+});
diff --git a/tests/utils/orcid.test.js b/tests/utils/orcid.test.js
new file mode 100644
index 0000000..3610b6d
--- /dev/null
+++ b/tests/utils/orcid.test.js
@@ -0,0 +1,124 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import { extractOrcidFromGithubHtml, extractOrcidFromGithubProfile, extractOrcidFromText } from '../../src/utils/orcid.js';
+import { isValidOrcidFormat, normalizeOrcid, stripOrcidUrl } from '../../src/utils/orcid.js';
+
+test('normalizeOrcid canonicalizes http ORCID URLs to https', () => {
+  assert.equal(
+    normalizeOrcid('http://orcid.org/0000-0002-1825-0097'),
+    'https://orcid.org/0000-0002-1825-0097',
+  );
+});
+
+test('normalizeOrcid canonicalizes plain ORCID identifiers to https URLs', () => {
+  assert.equal(
+    normalizeOrcid('0000-0002-1694-233X'),
+    'https://orcid.org/0000-0002-1694-233X',
+  );
+});
+
+test('normalizeOrcid keeps non-ORCID input unchanged', () => {
+  assert.equal(normalizeOrcid('https://foo.example/abc'), 'https://foo.example/abc');
+});
+
+test('normalizeOrcid does not double-prefix malformed ORCID-like input', () => {
+  assert.equal(
+    normalizeOrcid('https://orcid.org/https://foo.example/abc'),
+    'https://orcid.org/https://foo.example/abc',
+  );
+});
+
+test('stripOrcidUrl accepts bare orcid.org links without protocol', () => {
+  assert.equal(
+    stripOrcidUrl('orcid.org/0000-0002-1825-0097'),
+    '0000-0002-1825-0097',
+  );
+});
+
+test('extractOrcidFromText normalizes ORCID URLs', () => {
+  assert.equal(
+    extractOrcidFromText('https://orcid.org/0000-0002-1825-0097'),
+    'https://orcid.org/0000-0002-1825-0097',
+  );
+});
+
+test('extractOrcidFromText accepts plain ORCID identifiers', () => {
+  assert.equal(
+    extractOrcidFromText('0000-0002-1694-233X'),
+    'https://orcid.org/0000-0002-1694-233X',
+  );
+});
+
+test('extractOrcidFromGithubProfile checks attached social links before profile text', () => {
+  assert.equal(
+    extractOrcidFromGithubProfile(
+      {
+        blog: 'https://example.org/profile',
+        bio: 'Also reachable at 0000-0002-1694-233X',
+      },
+      [{ url: 'https://orcid.org/0000-0002-1825-0097' }],
+    ),
+    'https://orcid.org/0000-0002-1825-0097',
+  );
+});
+
+test('extractOrcidFromGithubProfile scans nested attached link fields', () => {
+  assert.equal(
+    extractOrcidFromGithubProfile(
+      {
+        blog: 'https://example.org/profile',
+        bio: 'Researcher in imageomics',
+      },
+      [{ provider: 'generic', metadata: { url: 'https://orcid.org/0000-0002-1825-0097' } }],
+    ),
+    'https://orcid.org/0000-0002-1825-0097',
+  );
+});
+
+test('extractOrcidFromGithubProfile scans arbitrary profile string fields', () => {
+  assert.equal(
+    extractOrcidFromGithubProfile({
+      blog: '',
+      bio: '',
+      note: 'Find me at orcid.org/0000-0002-1694-233X',
+    }),
+    'https://orcid.org/0000-0002-1694-233X',
+  );
+});
+
+test('extractOrcidFromGithubProfile checks blog before bio when no social ORCID is present', () => {
+  assert.equal(
+    extractOrcidFromGithubProfile({
+      blog: 'orcid.org/0000-0002-1825-0097',
+      bio: 'Also reachable at 0000-0002-1694-233X',
+    }),
+    'https://orcid.org/0000-0002-1825-0097',
+  );
+});
+
+test('extractOrcidFromGithubProfile returns null when no valid ORCID is present', () => {
+  assert.equal(
+    extractOrcidFromGithubProfile({
+      blog: 'https://example.org/profile',
+      bio: 'Researcher in imageomics',
+    }),
+    null,
+  );
+});
+
+test('extractOrcidFromGithubHtml finds ORCID links in HTML markup', () => {
+  assert.equal(
+    extractOrcidFromGithubHtml('<a href="https://orcid.org/0000-0002-1825-0097">ORCID</a>'),
+    'https://orcid.org/0000-0002-1825-0097',
+  );
+});
+
+test('isValidOrcidFormat accepts ORCID identifiers with valid checksum', () => {
+  assert.equal(isValidOrcidFormat('0000-0002-1825-0097'), true);
+  assert.equal(isValidOrcidFormat('https://orcid.org/0000-0002-1694-233X'), true);
+});
+
+test('isValidOrcidFormat rejects ORCID identifiers with invalid checksum', () => {
+  assert.equal(isValidOrcidFormat('0000-0002-1825-0098'), false);
+});
\ No newline at end of file
diff --git a/tests/validation/validation.test.js b/tests/validation/validation.test.js
new file mode 100644
index 0000000..9dab20d
--- /dev/null
+++ b/tests/validation/validation.test.js
@@ -0,0 +1,83 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import { normalizeFormInput, validateMetadata } from '../../src/validation/validation.js';
+
+const typeOptions = [
+  { value: 'article', label: 'Article' },
+  { value: 'dataset', label: 'Dataset' },
+  { value: 'software', label: 'Software' },
+  { value: 'other', label: 'Other' },
+];
+
+function createBaseForm() {
+  return {
+    title: 'OpenCite',
+    authors: [
+      {
+        givenNames: 'Jane',
+        familyNames: 'Doe',
+        orcid: 'https://orcid.org/0000-0002-1825-0097',
+        affiliation: 'Imageomics',
+      },
+    ],
+    license: 'MIT',
+    keywords: 'metadata, citation',
+    typeOfWork: 'software',
+    customTypeOfWork: '',
+    version: '1.2.3',
+    publicationDate: '2026-07-29',
+    repositoryCode: 'https://github.com/imageomics/OpenCite',
+    doi: '',
+    abstract: 'Metadata utility.',
+    references: '',
+    grants: '021nxhr62::2118240',
+  };
+}
+
+test('validateMetadata flags duplicate authors by normalized name', () => {
+  const form = createBaseForm();
+  form.authors.push({
+    givenNames: 'jane',
+    familyNames: 'doe',
+    orcid: '',
+    affiliation: '',
+  });
+
+  const normalized = normalizeFormInput(form);
+  const errors = validateMetadata(normalized, typeOptions);
+
+  assert.match(String(errors.authors ?? ''), /Duplicate author entries found/i);
+  assert.match(String(errors.authors ?? ''), /1, 2/);
+});
+
+test('validateMetadata flags duplicate authors by ORCID even when names differ', () => {
+  const form = createBaseForm();
+  form.authors.push({
+    givenNames: 'J.',
+    familyNames: 'Doe',
+    orcid: '0000-0002-1825-0097',
+    affiliation: '',
+  });
+
+  const normalized = normalizeFormInput(form);
+  const errors = validateMetadata(normalized, typeOptions);
+
+  assert.match(String(errors.authors ?? ''), /Duplicate author entries found/i);
+  assert.match(String(errors.authors ?? ''), /1, 2/);
+});
+
+test('validateMetadata accepts distinct authors', () => {
+  const form = createBaseForm();
+  form.authors.push({
+    givenNames: 'John',
+    familyNames: 'Smith',
+    orcid: 'https://orcid.org/0000-0003-1415-9267',
+    affiliation: '',
+  });
+
+  const normalized = normalizeFormInput(form);
+  const errors = validateMetadata(normalized, typeOptions);
+
+  assert.equal('authors' in errors, false);
+});