docs: add missing descriptions to contributor and item defs

[holkexyz]

Summary

• Added missing description to the contributor def on activity and the item def on collection.

Why

The lexicon style checker flags object defs without descriptions. More importantly, these descriptions appear in generated documentation and code comments, helping developers understand the purpose of each type without reading the full schema. The contributor and item defs were the only object types in the protocol missing descriptions.

Test plan

• npm run check passes
• Style checker no longer warns about missing descriptions

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation

  • Extended human-readable descriptions across many schema/lexicon definitions (contributors, items, scores, blobs, boards, links, etc.), improving clarity of documented fields and examples.

• Chores

  • Added a changeset for a minor release and updated the documentation generation so per-definition descriptions are included in the produced schema docs.

[changeset-bot]

🦋 Changeset detected

Latest commit: 07bd5fe

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@hypercerts-org/lexicon	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 4f8baf97-cf46-49fe-b572-714f023115f4

📥 Commits

Reviewing files that changed from the base of the PR and between 1c1e13e and 07bd5fe.

📒 Files selected for processing (5)

• .changeset/add-missing-def-descriptions.md
• SCHEMAS.md
• lexicons/org/hypercerts/claim/activity.json
• lexicons/org/hypercerts/collection.json
• scripts/generate-schemas.js

✅ Files skipped from review due to trivial changes (4)

• .changeset/add-missing-def-descriptions.md
• lexicons/org/hypercerts/claim/activity.json
• lexicons/org/hypercerts/collection.json
• SCHEMAS.md

🚧 Files skipped from review as they are similar to previous changes (1)

• scripts/generate-schemas.js

---

📝 Walkthrough

Walkthrough

This PR adds human-readable description fields to multiple lexicon defs (e.g., contributor, item, board configs) and updates the schema-generation script to conditionally emit those descriptions into SCHEMAS.md; no validation, types, or property names were changed.

Changes

Cohort / File(s)	Summary
Changelog / Release \.changeset/add-missing-def-descriptions.md	New changeset recording a minor version bump and documenting added def descriptions for the lexicon package.
Schema Docs SCHEMAS.md	Inserted plain-text description paragraphs for ~16 defs across multiple namespaces; only descriptive text was added, no schema structure changes.
Lexicon Definitions lexicons/org/hypercerts/claim/activity.json, lexicons/org/hypercerts/collection.json, lexicons/org/hypercerts/...	Added top-level description fields to defs such as contributor, item, and several others; properties, types, required flags, and refs unchanged.
Schema Generator scripts/generate-schemas.js	Adjusted additionalDefs rendering to conditionally include a def's description paragraph under its header instead of emitting an unconditional blank line, changing generated SCHEMAS.md formatting accordingly.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• add richtext facet for descriptions of activity claim #91 — Modifies the same lexicons/org/hypercerts/claim/activity.json contributor-related schema.
• change evidence.json to attachment.json and simplify #118 — Alters scripts/generate-schemas.js handling of def descriptions/markdown emission.
• auto-generate lexicon schema Markdown tables #97 — Earlier updates to generate-schemas.js that form the foundation for description rendering changes.

Suggested reviewers

• aspiers

Poem

🐇✍️ I hopped through defs with careful paws,
I tucked in words to fix small flaws,
Contributors, items — now they sing,
A tiny bloom from docstring spring,
Hooray, the lexicon takes wing!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: adding missing descriptions to contributor and item definition entries in the lexicon schema files.
Lexicon Documentation Sync	✅ Passed	Lexicon JSON files were modified with descriptions added to nested object defs, SCHEMAS.md was auto-generated with these descriptions, and ERD.puml remained unchanged as no entity relationships were added. Documentation is synchronized across all layers.
Lexicons Styleguide Compliance	✅ Passed	The pull request is fully compliant with the ATProto Lexicon Style Guide. Both modified definitions have descriptions and all properties have proper descriptions.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/add-missing-def-descriptions

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[s-adamantine]

We agreed during the call to add in missing descriptions, and this is a non-breaking change.

There is also a small change in the schema generation to update the schema markdown file. Now the markdown files also display the descriptions.

[s-adamantine]

I ran another AI to check if there were missing descriptions elsewhere, and it didn't find any. LGTM.