Feature: GitHub metadata import for OpenCite

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.

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/