# Contributing to OpenAgreements

Thanks for your interest in contributing! OpenAgreements is an open-source tool for filling standard legal agreement templates. Contributions of new templates, recipe improvements, bug fixes, and documentation are welcome.

Please follow our [Code of Conduct](CODE_OF_CONDUCT.md) in all project spaces.

## Ways to Contribute

### Add a Template

The most impactful contribution is adding a new template. Requirements:

- Source document must be **CC BY 4.0** or **CC0** licensed
- Available as DOCX with fillable fields

See [docs/adding-templates.md](docs/adding-templates.md) for the full guide.

### Template credits

Templates may carry a `credits` array naming individuals who materially shaped them. Credit is a form of recognition for substantive work.

- **Credit requires a material, template-specific contribution.** Typo fixes, formatting, or metadata touch-ups don't qualify for template-level credit, even if merged.
- **Consent is required.** No one is added to `credits` without their explicit agreement. Anyone named can ask to be removed at any time.
- **Honest role labels:**
  - `drafter` — originated the template or distinctive clause architecture
  - `drafting_editor` — materially synthesized/adapted external sources into the published form
  - `reviewer` — substantive legal review of drafted text
  - `maintainer` — ongoing stewardship (not authorship)

### Add a Recipe

Recipes handle documents that aren't redistributable (e.g., NVCA model documents). You author transformation instructions — never commit the source DOCX.

See [docs/adding-recipes.md](docs/adding-recipes.md) for the full guide.

### Report a Bug

Open an issue with:
- What you expected to happen
- What actually happened
- The command you ran
- Your Node.js version (`node -v`)

### Improve Documentation

Docs live in `docs/`. Fix typos, clarify instructions, or add examples.

### Add Your Project to "Built With OpenAgreements"

If you've built something on OpenAgreements, we'd love to feature it. Open a PR adding a one-liner here:

*No projects listed yet — be the first!*

## Development Setup

```bash
git clone https://github.com/open-agreements/open-agreements.git
cd open-agreements
npm install
npm run build
npm run test:run
```

## Before Submitting a PR

1. **Build**: `npm run build` passes
2. **Lint**: `npm run lint` passes
3. **Test**: `npm run test:run` passes (all 81+ tests)
4. **Validate**: `node bin/open-agreements.js validate` passes for all templates and recipes
5. **Preview freshness** (OA-owned templates only): if you modified a template's
   `template.md` (canonical templates), `template.json` (the JSON-spec template),
   or `template.docx`, or any renderer/generator script (e.g., under
   `scripts/template_renderer/`, `scripts/generate_templates.mjs`,
   `scripts/template-specs/styles/openagreements-default-v1.json`,
   `scripts/generate_checklist_template.mjs`,
   `scripts/generate_working_group_template.mjs`), regenerate the affected
   previews locally and commit them in the same PR:

   ```
   npm run generate:templates                              # if you edited template.md / template.json
   npm run generate:template-previews -- --template <template-id>
   # or for a renderer-pipeline change that fans out to many templates:
   npm run generate:template-previews
   ```

   Commit the updated `site/assets/previews/<id>/page-*.png` (and any
   regenerated `template.docx` / `.template.generated.json`). CI's
   `preview-freshness-gate` enforces this on PRs.

   Note: `metadata.yaml` is catalog-only (not a render input), so editing it
   does **not** require a preview refresh.

6. **LLM-Based Quality Gate**: same-repo PRs are reviewed by an LLM-powered
   code-reuse detector in `.github/workflows/llm-based-quality-gate.yml`. The
   pre-merge gate runs when a PR is opened, marked ready for review, or has the
   `llm-gate/override` label added or removed; it does not re-run on every
   iteration push. If a verdict is stale after a fix, maintainers can manually
   re-run it from Actions or with
   `gh workflow run llm-based-quality-gate.yml --field pr_number=<number>`.
   By default the pre-merge gate is advisory: it posts PASS/WARN findings as a
   PR comment but does not block merging. Maintainers can enable blocking mode
   with the `LLM_GATE_BLOCKING=1` repo variable; in that mode any WARN row fails
   the aggregate check unless the PR has the `llm-gate/override` label, which
   keeps the findings visible while treating them as non-blocking for that PR.
   After merge, `.github/workflows/llm-based-quality-gate-post-merge.yml` runs
   an audit on the diff that landed on `main` and comments on the merged PR; the
   audit is informational and never blocks `main`.

## Project Structure

```
content/
  templates/        # Internal templates (CC BY 4.0) — we ship the DOCX
  external/         # External templates (CC BY-ND 4.0) — vendored unchanged
  recipes/          # Recipes (not redistributable) — instructions only, DOCX downloaded at runtime
src/                # TypeScript source + collocated unit tests
integration-tests/  # Integration and end-to-end tests
skills/             # Agent Skills (Claude Code, Cursor, etc.)
docs/               # Documentation
```

## Releasing

Releases are automated through GitHub Actions using npm trusted publishing (OIDC) with provenance enabled.

1. Update versions in root package + publishable MCP packages.
2. Push commit + tag with `git push origin main --tags`
3. Run the local Gemini extension gate (copy/symlink into `~/.gemini/extensions/open-agreements` and verify both local MCP servers start/respond).
4. The `Release` workflow publishes from the tag after running build, validation, tests, isolated runtime smoke, and package checks.

Workflow guardrails:

- Tag must match root + publishable package versions
- Release commit must be contained in `origin/main`
- Publish fails if any target npm version already exists

## Architecture

- **Language**: TypeScript
- **DOCX Engine**: [docx-templates](https://www.npmjs.com/package/docx-templates) (MIT)
- **CLI**: [Commander.js](https://www.npmjs.com/package/commander)
- **Validation**: [Zod](https://www.npmjs.com/package/zod) schemas
- **Skill Pattern**: Agent-agnostic `ToolCommandAdapter` interface

```
content/                    # All content directories
├── templates/              # Internal templates (CC BY 4.0)
├── external/               # External templates (CC BY-ND 4.0)
└── recipes/                # Recipes (downloaded at runtime)

src/                        # TypeScript source + collocated unit tests
├── cli/                    # Commander.js CLI
├── commands/               # fill, validate, list, recipe, scan
├── core/
│   ├── engine.ts           # docx-templates wrapper
│   ├── metadata.ts         # Zod schemas + loader
│   ├── recipe/             # Recipe pipeline (clean → patch → fill → verify)
│   ├── external/           # External template support
│   ├── validation/         # template, license, output, recipe
│   └── command-generation/
│       ├── types.ts        # ToolCommandAdapter interface
│       └── adapters/       # Claude Code adapter
└── index.ts                # Public API

integration-tests/          # Integration and end-to-end tests
```

## License

By contributing, you agree that your contributions will be licensed under the Apache License 2.0. Template content retains the license of its source (CC BY 4.0, CC0, or CC BY-ND 4.0).
