Improve contributor onboarding and policy docs

[dimaMachina]

Summary

• Added clearer contributor guidance for CLA signing, internal review flow, stale PR handling, and changeset requirements.
• Aligned pre-1.0 changeset bump rules across contributor-facing docs.
• Added a PR template plus new SECURITY.md and CODE_OF_CONDUCT.md files.
• Clarified the CLA wording to say it is adapted from Apache ICLA text and added corporate CLA next-step guidance.

Testing

• bun run lint:biome passed.
• bun run check failed in unrelated packages/app tests; the failures are outside the docs touched by this PR.
• Verified the updated docs and new support files exist and the contributor guidance is internally consistent.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
open-knowledge-docs	Ready	Preview, Comment	Jun 5, 2026 4:28pm

[inkeep-internal-ci]

Claude finished @dimaMachina's task in 8m 48s —— View job

---

PR Review Complete ✅

• Phase 1: Analyze context & load workflow
• Phase 2: Triage — dispatched 4 reviewers
• Phase 3: Collected findings (docs scoped out, consistency: 5, product: 5, precision: 3)
• Phase 4: Arbitrated & deduplicated → 7 actionable findings
• Phase 5: Added 2 inline comments to pending review
• Phase 6: Submitted final review — Approve with Suggestions

Result: 1 Minor (changeset category ambiguity) · 5 Consider · 1 While You're Here · 4 Discarded

[inkeep-internal-ci]

PR Review Summary

(7) Total Issues | Risk: Low

🟡 Minor (1) 🟡

🟡 1) .changeset/README.md:23-28 · AGENTS.md:62 · CONTRIBUTING.md:105-106 Ambiguous bump category for mid-sized features

Issue: The old changeset table had an explicit row: "New feature, additive API surface → minor." The new table replaces it with "Large new surface → minor" and "Bug fix, UI improvement, or small user-visible addition → patch." This leaves an uncovered middle ground: a contributor adding a new CLI flag, a new MCP tool, or a new editor command can't confidently determine whether it qualifies as "large" (→ minor) or "small" (→ patch). The same ambiguity is consistently present in all three locations where bump rules are documented.

Why: The old "additive API surface" row was a catch-all for features; now, the distinction relies on a subjective size judgment ("large" vs. "small") with no examples or heuristic to guide the decision. This is especially impactful for external contributors who lack team context about what counts as "large."

Fix: Add a brief clarifying parenthetical or examples in .changeset/README.md (the most authoritative source) to define the boundary. For example:

| Large new surface (new editor feature, new MCP tool, new CLI command) | `minor` |
| Bug fix, UI improvement, or small addition to an existing surface     | `patch` |

Then propagate the same clarifying language to AGENTS.md and CONTRIBUTING.md so all three stay aligned.

Refs:

• .changeset/README.md:23-28 — new table
• AGENTS.md:62 — inline bump guidance
• CONTRIBUTING.md:105-106 — changesets section

💭 Consider (5) 💭

💭 1) CLA.md:33 · CONTRIBUTING.md:28 Corporate CLA paragraph verbatim-duplicated across two files

Issue: The corporate CLA next-step sentence appears identically in both CLA.md and CONTRIBUTING.md, with a minor phrasing divergence ("your PR" vs. "your pull request"). Two homes for the same policy text means a future process change must be made in both places.
Why: CONTRIBUTING.md already links to CLA.md as the source of truth for signing instructions (line 26). Repeating the corporate-CLA paragraph rather than cross-referencing creates a drift hazard.
Fix: In CONTRIBUTING.md, replace the verbatim sentence with a cross-reference: "For corporate CLAs, see CLA.md."
Refs: CLA.md:33 · CONTRIBUTING.md:28

💭 2) CODE_OF_CONDUCT.md:25 Enforcement section lacks a concrete reporting channel

Issue: The enforcement section says "contact an Inkeep maintainer privately when possible" but provides no email, GitHub username, or link. SECURITY.md names a concrete channel (incidents@inkeep.com); the CoC does not.
Why: A contributor trying to report harassment cannot act on this instruction without guessing how to reach a maintainer privately. The more sensitive report type (conduct) has a less specific path than vulnerability reports.
Fix: Add a contact mechanism — either reuse incidents@inkeep.com or add a dedicated conduct email. Alternatively, cross-reference SECURITY.md's email if that channel is intentionally shared.
Refs: CODE_OF_CONDUCT.md:25 · SECURITY.md:7

💭 3) SECURITY.md:14 Acknowledgement SLA is vague

Issue: "We will acknowledge reports as soon as practical" gives no fallback timeframe. Reporters who receive no response will often escalate publicly or assume the report was lost.
Why: A soft commitment like "within 5 business days" (common for projects this size) significantly improves reporter confidence without binding to a hard SLA.
Fix: Consider adding: "We aim to acknowledge within 5 business days. If you have not heard back, reply to your original email."
Refs: SECURITY.md:14

Inline Comments:

• 💭 Consider: .github/pull_request_template.md:5-7 "Verification" section has a bare placeholder with no guidance on expected content
• 💭 Consider: AGENTS.md:62 Dropped "most changesets are patch" frequency heuristic useful for agent decision-making

🧹 While You're Here (1) 🧹

🧹 1) .changeset/README.md:36 bun changeset vs bun run changeset inconsistency

Issue: .changeset/README.md line 36 says "run bun changeset" while AGENTS.md line 61 and CONTRIBUTING.md line 99 both use bun run changeset. Both forms work, but the inconsistency may confuse contributors who consult multiple docs.
Why: This PR just aligned changeset bump rules across all three files — normalizing the command form would complete the alignment.
Fix: Change .changeset/README.md line 36 from bun changeset to bun run changeset.
Refs: .changeset/README.md:36 · AGENTS.md:61 · CONTRIBUTING.md:99

---

💡 APPROVE WITH SUGGESTIONS

Summary: Clean, well-scoped docs PR that adds valuable contributor onboarding infrastructure (SECURITY.md, CODE_OF_CONDUCT.md, PR template) and aligns changeset rules across three documents. The main actionable item is clarifying the boundary between minor and patch for mid-sized features — adding examples to the bump-rules table would eliminate the ambiguity the old "New feature" row previously covered. The remaining items are small consistency and discoverability improvements.

Discarded (4)

Location	Issue	Reason Discarded
CODE_OF_CONDUCT.md	Custom CoC vs Contributor Covenant	Deliberate design decision; the custom CoC is materially adequate and the choice is a maintainer preference, not a defect.
CLA.md:1	Header change from "Based on" to "Adapted from" removes transparency about verbatim Apache text	LOW confidence — "Adapted from" is arguably more accurate given the additions, and the body text is unchanged so contributors can still compare.
.github/pull_request_template.md	Missing Code of Conduct acknowledgement checkbox	CoC is a general behavior expectation, not a per-PR action like CLA signing. Adding it would over-checklist the template.
multi-file	Changeset rules in 3 places should have a single source of truth	Intentional information architecture — each doc serves a different audience (agents, contributors, changeset authors). The 3 copies are in sync as of this PR.

Reviewers (4)

Reviewer	Returned	Main Findings	Consider	While You're Here	Inline Comments	Pending Recs	Discarded
pr-review-consistency	5	1	1	1	0	0	2
pr-review-product	5	0	2	0	1	0	2
pr-review-precision	3	0	1	0	1	0	1
pr-review-docs	0	0	0	0	0	0	0
Total	13	1	4	1	2	0	5

Note: pr-review-docs correctly scoped out — all changed files are internal contributor/policy docs, not customer-facing documentation in the docs site roots. Findings were deduplicated across consistency/product/precision (corporate CLA duplication and CoC contact gap raised by multiple reviewers).

[inkeep-internal-ci]

💭 Consider — "Verification" section purpose is unclear

Issue: The "Verification" section is a bare bullet placeholder (-) with no guidance on what content it expects. First-time contributors will likely skip it or duplicate their Summary text, since the two sections look identical.

Why: The checklist item on line 12 ("I added tests or a manual verification note") implies this is where that note should go — but the section header alone doesn't convey that. A brief HTML comment would make the section self-documenting without adding visual noise.

Fix: (1-click apply)

Suggested change

	## Verification
	-
	## Verification
	<!-- What did you run or observe to confirm the change works? (test command, screenshot, manual steps) -->
	-

Refs:

• PR template checklist L12 — the verification checklist item that this section supports

[inkeep-internal-ci]

💭 Consider — Dropped frequency heuristic useful for agent decision-making

Issue: The rewrite removed the operational heuristic "Most changesets are patch. minor is rare" that was in the previous text. AGENTS.md is the primary doc parsed by AI agents choosing a bump type — the frequency prior ("reach for patch by default") is arguably the most decision-useful signal for an agent resolving ambiguous cases.

Why: The mapping rules tell you what each level means; the frequency heuristic tells you which to reach for under uncertainty. Dropping it slightly raises the chance an agent over-classifies a change as minor.

Fix: (1-click apply)

Suggested change

	- Bump type: use `patch` for bug fixes, UI improvements, and small user-visible additions; use `minor` for breaking API, schema, or CLI changes, and for large new surfaces. **Never declare `major` pre-1.0** (see the `"//"` line in `.changeset/config.json`).
	- Bump type: use `patch` for bug fixes, UI improvements, and small user-visible additions; use `minor` for breaking API, schema, or CLI changes, and for large new surfaces — most changesets are `patch`. **Never declare `major` pre-1.0** (see the `"//"` line in `.changeset/config.json`).

Refs:

• .changeset/README.md:36 — authoring tip in the changeset README carries similar framing