docs + fix: sync SKILL.md, normalize linearDocument ref, correct changeset

[s-adamantine]

Follow-ups to the freshly-merged PR #174 (now on main).

Summary

1. Sync SKILL.md with README. The Organization row in .agents/skills/building-with-hypercerts-lexicons/SKILL.md was not updated alongside README.md:273, violating AGENTS.md:241–248 which requires both files stay in sync when either references a lexicon. Downstream AI agents installing the skill via npx skills add hypercerts-org/hypercerts-lexicon were seeing a stale overview row.

2. Normalize longDescription ref. In PR NON-BREAKING: add optional longDescription and visibility fields to organization #174 the new Leaflet variant on app.certified.actor.organization was added as pub.leaflet.pages.linearDocument#main, but the peer lexicons (activity, collection, attachment) already use the bare pub.leaflet.pages.linearDocument form after cleanup commit 06fce2c. PR NON-BREAKING: add optional longDescription and visibility fields to organization #174 was rebased onto that cleanup but re-introduced the redundant #main. Dropping it restores consistency at the ref-string level. Purely a syntactic normalization — the target def is unchanged.

3. Fix unreleased changeset wording. .changeset/add-organization-page-and-visibility.md described longDescription as a 2-way union, but the actual schema has three variants (inline string / embedded Leaflet linear document / strongRef). Rewrote the description so the v0.12.0 CHANGELOG entry accurately reflects the schema and the "consistency with activity, collection, attachment" claim is truthful after fix Hypercert Sale Lexicon #2.

Test plan

• npm run check (validate + typecheck + build + 135 tests pass)
• Spot-check rendered SKILL.md Certified overview table on GitHub
• Verify the updated changeset produces the intended v0.12.0 CHANGELOG entry when the Release PR bot next runs

🤖 Generated with Claude Code

[coderabbitai]

📝 Walkthrough

Walkthrough

Updated documentation and schema for the Organization certified lexicon: SKILL.md table row for app.certified.actor.organization now lists foundedDate, longDescription, and visibility; the longDescription union in lexicons/app/certified/actor/organization.json now references pub.leaflet.pages.linearDocument (removed #main). Two changesets documenting these syncs were added/updated.

Changes

Cohort / File(s)	Summary
Documentation .agents/skills/building-with-hypercerts-lexicons/SKILL.md	Expanded "Certified — shared lexicons" table Purpose for app.certified.actor.organization to include foundedDate, longDescription, and visibility; adjusted table column spacing/alignment.
Schema lexicons/app/certified/actor/organization.json	Updated defs.main.record.properties.longDescription union: changed reference pub.leaflet.pages.linearDocument#main → pub.leaflet.pages.linearDocument.
Changesets / Release docs .changeset/sync-skill-organization-fields.md, .changeset/add-organization-page-and-visibility.md	Added/updated changesets (patch) documenting synchronization of SKILL.md with README fields and clarifying longDescription union variants and description patterns; no runtime code changes.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• feat: add app.certified.actor.organization sidecar lexicon #140: modifies app.certified.actor.organization schema and organization sidecar — closely related.
• NON-BREAKING: add optional longDescription and visibility fields to organization #174: also adjusts app.certified.actor.organization longDescription/visibility sync — directly related.
• fix: widen description fields from Leaflet ref to union type #181: touches long-form description union variants and Leaflet linearDocument references — related to the schema change here.

Suggested reviewers

• aspiers
• daviddao
• holkexyz

Poem

🐰 With nibble and hop I proof the line,

I tuck new fields where orgs can shine;
Founding dates, long notes, and visibility too,
Docs and schema tidy—fresh as dew;
Hop-hop hooray, the lexicon's new! ✨

🚥 Pre-merge checks | ✅ 7

✅ Passed checks (7 passed)

Check name	Status	Explanation
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	PR modifies organization.json to normalize longDescription reference from pub.leaflet.pages.linearDocument#main to pub.leaflet.pages.linearDocument, aligning with other lexicons without structural changes.
Lexicons Styleguide Compliance	✅ Passed	The lexicon file lexicons/app/certified/actor/organization.json fully complies with the AT Protocol lexicon styleguide. The PR normalizes the longDescription union reference consistently with activity, collection, and attachment lexicons.
Title check	✅ Passed	The title accurately summarizes the main changes: documentation updates to sync SKILL.md, a schema reference fix for linearDocument, and changeset corrections.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ 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/skill-organization-sync

---

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

[changeset-bot]

🦋 Changeset detected

Latest commit: 89d1bd9

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]

LGTM — docs sync plus a ref normalization (drops #main to match the other lexicons that reference linearDocument).

Extended reasoning...

Overview

Small, mostly-documentation PR that (1) syncs the SKILL.md Certified lexicons overview row for Organization with README.md by listing the new foundedDate, longDescription, and visibility fields, (2) adds a patch changeset for the SKILL.md sync, (3) tightens the existing minor changeset's wording, and (4) normalizes the longDescription union ref in lexicons/app/certified/actor/organization.json from pub.leaflet.pages.linearDocument#main to pub.leaflet.pages.linearDocument.

Security risks

None. No auth, crypto, or permission logic is touched. The lexicon ref normalization only affects schema validation expectations.

Level of scrutiny

Low. SKILL.md and changeset edits are user-facing docs but purely textual. The one lexicon edit is a mechanical consistency fix: collection.json, context/attachment.json, and claim/activity.json already reference pub.leaflet.pages.linearDocument without the #main suffix, so this brings organization.json in line with the established pattern in this repo.

Other factors

No bugs were flagged by the bug hunter. CodeRabbit's pre-merge checks all pass. The SKILL.md change simply mirrors content that already exists in README.md per the AGENTS.md sync requirement.