Polish public release documentation

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,42 @@
+---
+name: Bug report
+about: Report a reproducible problem in Parcel Society
+title: "[Bug]: "
+labels: bug
+assignees: ""
+---
+
+## Summary
+
+Describe the bug clearly and briefly.
+
+## Steps to reproduce
+
+1.
+2.
+3.
+
+## Expected behavior
+
+What should have happened?
+
+## Actual behavior
+
+What happened instead?
+
+## Environment
+
+- OS:
+- Browser:
+- Node version:
+- pnpm version:
+- Docker version, if relevant:
+- Commit SHA or release:
+
+## Logs or screenshots
+
+Paste relevant logs or add screenshots. Do not include credentials, private participant data, or unpublished study data.
+
+## Impact
+
+Does this affect local development, pilots, data exports, participant flow, deployment, or analysis?

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,30 @@
+---
+name: Feature request
+about: Propose a small, research-oriented improvement
+title: "[Feature]: "
+labels: enhancement
+assignees: ""
+---
+
+## Summary
+
+Describe the requested change.
+
+## Motivation
+
+Why is this needed? If it changes participant experience, game mechanics, exports, or analysis, explain the research reason.
+
+## Proposed behavior
+
+What should the feature do?
+
+## Alternatives considered
+
+What simpler options or workarounds have you considered?
+
+## Scope and risks
+
+- Does this affect study design?
+- Does this affect data exports?
+- Does this affect privacy or ethics?
+- Does this require documentation updates?

.github/ISSUE_TEMPLATE/research_question.md

@@ -0,0 +1,27 @@
+---
+name: Research question
+about: Research discussion or design proposal
+title: "[Research]: "
+labels: research
+assignees: ""
+---
+
+## Research question
+
+State the question or hypothesis.
+
+## Construct and measurement
+
+What concept should Parcel Society measure, and which in-app behavior or export field would represent it?
+
+## Design implications
+
+Does this require new mechanics, changed instructions, new randomization, or additional exports?
+
+## Analysis plan
+
+How would the outcome be analyzed? Note the unit of analysis and any clustering concerns.
+
+## Ethics and privacy
+
+Does the proposal change participant risk, consent language, data minimization, or disclosure risk?

.github/pull_request_template.md

@@ -0,0 +1,25 @@
+## Summary
+
+-
+
+## Research/design impact
+
+- [ ] No participant-facing behavior changes
+- [ ] No game-mechanics changes
+- [ ] No export or analysis changes
+- [ ] Documentation updated if needed
+
+Explain any checked exceptions or research implications:
+
+## Testing
+
+- [ ] `pnpm typecheck`
+- [ ] `pnpm lint`
+- [ ] `pnpm test`
+- [ ] `pnpm build`
+- [ ] Docker Compose checked, if relevant
+
+## Privacy and data safety
+
+- [ ] No credentials, private data, database dumps, or participant identifiers added
+- [ ] Export/privacy implications reviewed, if relevant

CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+All notable changes to Parcel Society will be documented in this file.
+
+The format follows the spirit of [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project uses semantic versioning for public releases.
+
+## [0.1.0] - 2026-05-10
+
+### Added
+
+- Initial public research-software release of Parcel Society.
+- Next.js web app with participant and admin foundations.
+- Prisma/PostgreSQL data model, seed scripts, and deterministic demo dataset.
+- Engine package for maps, decisions, contracts, shocks, scoring, and round resolution.
+- Research-safe CSV/ZIP export endpoints and data dictionary.
+- Documentation for research design, mechanics, analysis, admin operations, deployment, and ethics.
+- Docker Compose files for local and production-oriented starts.
+- Contributor guide, Code of Conduct, issue templates, and pull request template.

CODE_OF_CONDUCT.md

@@ -0,0 +1,33 @@
+# Code of Conduct
+
+## Our pledge
+
+We pledge to make participation in Parcel Society welcoming, respectful, and harassment-free for contributors and users regardless of background, identity, experience level, or research role.
+
+## Expected behavior
+
+- Be respectful and constructive.
+- Assume good intent while being accountable for impact.
+- Discuss research and technical tradeoffs with evidence and clarity.
+- Keep criticism focused on ideas, code, documentation, and study design.
+- Respect privacy and never share participant data, credentials, or private communications without permission.
+
+## Unacceptable behavior
+
+- Harassment, threats, insults, or discriminatory language.
+- Sexualized language or unwelcome attention.
+- Publishing private information without explicit permission.
+- Sharing confidential research data or participant information.
+- Repeated disruption of discussions or maintainers' decisions.
+
+## Enforcement
+
+Maintainers may remove comments, close issues, reject contributions, or restrict participation when behavior harms the community or the responsible use of the project. Enforcement should be proportionate, documented when appropriate, and focused on protecting contributors and research participants.
+
+## Reporting
+
+Report concerns privately to the project maintainers. Include links, screenshots, or context when safe to do so. Do not include sensitive participant data unless it is necessary and appropriate for the report.
+
+## Scope
+
+This Code of Conduct applies in project repositories, issue trackers, pull requests, discussions, and any community spaces associated with Parcel Society.

CONTRIBUTING.md

@@ -0,0 +1,88 @@
+# Contributing to Parcel Society
+
+Thank you for helping improve Parcel Society. Contributions should keep the project simple, stable, and research-oriented.
+
+## Set up locally
+
+```bash
+corepack enable
+pnpm install
+cp .env.example .env
+docker compose up -d postgres
+pnpm db:generate
+pnpm db:migrate
+pnpm seed:demo
+pnpm dev
+```
+
+Open <http://localhost:3000> for the app and <http://localhost:3000/admin/login> for the admin area.
+
+## Branch naming
+
+Use short, descriptive branch names:
+
+- `docs/readme-release-polish`
+- `fix/export-empty-contracts`
+- `test/round-resolver-edge-cases`
+- `chore/update-dependencies`
+
+Avoid vague names such as `changes`, `misc`, or `final`.
+
+## Coding style
+
+- Use TypeScript for application and package code.
+- Keep mechanics deterministic where the research design requires reproducibility.
+- Prefer small functions with explicit types at package boundaries.
+- Do not add gameplay mechanics without a research-design justification.
+- Keep participant-facing language clear and consistent.
+- Never commit `.env`, database dumps, participant data, or private credentials.
+- Run formatting before submitting broad Markdown or TypeScript edits.
+
+## Tests and checks
+
+Run these before opening a pull request:
+
+```bash
+pnpm typecheck
+pnpm lint
+pnpm test
+pnpm build
+```
+
+When changing database schema or seed behavior, also run:
+
+```bash
+pnpm db:generate
+pnpm db:migrate
+pnpm seed:demo
+```
+
+When changing Docker or deployment files, test the relevant Compose file:
+
+```bash
+docker compose up --build
+docker compose -f docker-compose.prod.yml up --build
+```
+
+## Opening issues
+
+Use the GitHub issue templates when possible:
+
+- Bug reports should include reproduction steps, expected behavior, actual behavior, and logs or screenshots.
+- Feature requests should explain the research or maintenance reason for the change.
+- Research questions should state the construct, proposed measurement, and expected export fields.
+
+Please do not file issues containing private participant data, credentials, or unpublished study data.
+
+## Good first issues
+
+Good first contributions usually have low design risk:
+
+- Improve documentation clarity.
+- Add tests for validation and engine edge cases.
+- Improve accessibility labels and keyboard navigation.
+- Add export consistency checks.
+- Improve error messages without changing behavior.
+- Add screenshots or diagrams to `docs/images/`.
+
+For larger changes, open an issue first so maintainers can discuss scope and research implications.