feat: add app.certified.graph.follow lexicon

[s-adamantine]

Fixes HYPER-399

Adds a social-graph follow record under the app.certified namespace that is schema-compatible with app.bsky.graph.follow:

• same record key (tid)
• same required fields (subject: did, createdAt: datetime)
• same optional via field (com.atproto.repo.strongRef)
• same lexicon description

This lets feed-builders and view services index certified.app follows with the same logic they already use for Bluesky follows, and gives the certified.app ecosystem a primitive social graph.

Also includes:

• generated TypeScript types and exports (GRAPH_FOLLOW_NSID, GRAPH_FOLLOW_LEXICON_JSON / DOC, AppCertifiedGraphFollow)
• 8 validation tests in tests/validate-graph-follow.test.ts
• regenerated SCHEMAS.md
• README.md, SKILL.md, and ERD.puml updates documenting the new lexicon
• changeset (minor)

The strongref-documentation linter rule is satisfied by noting in the via description that the referenced record may conform with any lexicon (mirroring bsky's open use of the field for things like starter packs).

Summary by CodeRabbit

• New Features

  • Added a certified social-graph "follow" primitive for account-to-account relationships, with optional mediator references.

• Documentation

  • Added guides and a TypeScript example for constructing follow records.
  • Updated lexicon listings, schema reference, README, and relationship diagrams to include Follow.

• Tests

  • Added validation tests ensuring required fields, optional mediator refs, and proper formats.

[changeset-bot]

🦋 Changeset detected

Latest commit: 637fe3b

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

[claude]

Claude Code Review

This repository is configured for manual code reviews. Comment @claude review to trigger a review and subscribe this PR to future pushes, or @claude review once for a one-time review.

_{Tip: disable this comment in your organization's Code Review settings.}

[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: 2fcb12cb-30bf-4fe4-bfcb-4843e7b2089f

📥 Commits

Reviewing files that changed from the base of the PR and between 1fb096c and 637fe3b.

📒 Files selected for processing (2)

• .agents/skills/building-with-hypercerts-lexicons/SKILL.md
• README.md

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

• README.md
• .agents/skills/building-with-hypercerts-lexicons/SKILL.md

---

📝 Walkthrough

Walkthrough

Adds a new certified lexicon app.certified.graph.follow (JSON + SCHEMAS.md), exports constants/types via a changeset, documents the lexicon and example usage in README/SKILL, updates ERD relationships, and adds Vitest validation tests covering positive and negative cases.

Changes

App Certified Graph Follow Lexicon

Layer / File(s)	Summary
Data Shape lexicons/app/certified/graph/follow.json, SCHEMAS.md	Lexicon app.certified.graph.follow defined as a record keyed by tid with required subject (DID string) and createdAt (datetime string), plus optional via strongRef field.
Type Exports & Changeset .changeset/add-graph-follow-lexicon.md	Changeset declares minor version update and exports GRAPH_FOLLOW_NSID, GRAPH_FOLLOW_LEXICON_JSON, GRAPH_FOLLOW_LEXICON_DOC constants and AppCertifiedGraphFollow type namespace under @hypercerts-org/lexicon.
Entity Relationship Mapping ERD.puml	New follow dataclass entity added with subject, optional via, and createdAt fields; relationship arrow added from follow::subject to contributorEntity labeled "follows".
Documentation & Examples README.md, .agents/skills/building-with-hypercerts-lexicons/SKILL.md	Lexicon reference tables and "Following another account" pattern section added with TypeScript example showing record construction using GRAPH_FOLLOW_NSID, mirroring app.bsky.graph.follow behavior.
Tests tests/validate-graph-follow.test.ts	Vitest suite validating positive cases (minimal and with optional via), and negative cases covering missing required fields, invalid DID/datetime formats, missing strongRef fields, and missing $type.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related issues

• Expand app.certified.graph.* with the rest of the social-graph primitives #210 — related work proposing app.certified.graph.* primitives; overlaps with this PR's addition of app.certified.graph.follow.

Possibly related PRs

• hypercerts-org/hypercerts-lexicon#195 — updates the same skill guide and lexicon references, similar doc surface edits.

Suggested reviewers

• Kzoeps
• aspiers

Poem

I stitched a follow from DID and time,
A tidy record, simple and prime.
With via optional, links align,
The graph extends one gentle line.
🐇✨

🚥 Pre-merge checks | ✅ 7

✅ Passed checks (7 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The pull request title clearly and concisely describes the main change: adding a new lexicon definition for app.certified.graph.follow.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Lexicon Documentation Sync	✅ Passed	follow.json, README.md, SCHEMAS.md, and ERD.puml are synchronized. All properties (subject, createdAt, via) documented correctly with matching descriptions and valid relationships across all files.
Lexicons Styleguide Compliance	✅ Passed	New app.certified.graph.follow lexicon passes all style guide checks; zero automated linter issues found. Proper naming, descriptions, schema design, strongRef documentation, and string constraints.

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature/add-graph-follow-lexicon

---

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]

Filed #210 to track the follow-up lexicons (block, list + listitem, listblock, starterpack, verification) discovered while scoping this PR.

[aspiers]

LGTM