[seanspeaks]

What changed (Diátaxis)

• Reference — updated docs/reference/api-module-definition-and-functions.md against the schema on next and real v1-ready examples (Fathom ≈ form-based, HubSpot ≈ redirect + code). Fixed root-absolute / broken links.
• How-to — replaced the hidden stub docs/api-module-library/building-your-own-module.md with Contribute an API Module for landing a package on api-module-library next.
• SUMMARY / overview — title + links updated; module list still points at GitHub packages/v1-ready/ (no empty stub fleshing).

Merged sources checked

Source	Notes
packages/schemas/schemas/api-module-definition.schema.json on frigg next	Field list for 2.11
frigg validate via #666 on next	App-definition validation only; structural module checks when listed on an app
api-module-library next — packages/v1-ready/fathom, hubspot	Layout, auth patterns, package name/@friggframework/core range
frigg next — .claude/skills/frigg-api-modules/SKILL.md + references/auth-testing.md	Skill lives on frigg next (not on main today)
#701	Still OPEN — gated modelName / getAuthorizationRequirements / setAuthParams schema allowance and standalone frigg validate --module

Module Builder corrections applied (override original ASSUMPTIONs)

1. PR title format to cite: feat(<slug>): add <DisplayName> API module
2. Prefer Fathom for package/file/test layout; HubSpot for redirect/getToken + extensions/webhooks
3. Auth checklist: always API / getName / moduleName + entity/credential/persist/testAuth + env. Then by flow — redirect + code: getToken + redirect_uri ternary; form-based: getAuthorizationRequirements + setAuthParams (API key common, not exclusive); hybrid: both. modelName optional in prose.
4. Teach redirect_uri ternary; do not copy HubSpot’s always-on template string
5. No Definition.mappings; extensions.mapping out of scope for a minimal first contrib
6. Soft public blurb (no internal bots / release tooling named)
7. Capabilities (ADR-020) emerging/optional — not a contrib gate; omit capability-manifest / UI-spec from requirements
8. Gates today: npm test (+ optional frigg auth test .); do not require unreleased validate/canary

Follow-up: auth framing (Sean)

Prose no longer frames auth as a hard API-key vs OAuth split. Docs use redirect + code / form-based / OAuth with a pre-redirect form, with the same method mapping (getToken for redirect; form methods for forms; hybrid uses both). Templates stay Fathom ≈ form, HubSpot ≈ redirect.

ASSUMPTIONS (still call out)

• Exact @friggframework/core pin cited as “read a sibling package.json”; Fathom on library next was ^2.0.0-next.107 at write time — range may move.
• If docs publish from frigg main, skill deep-links to blob/next/... may 404 until the skill lands on main (called out on the contribute page).
• Schema vs library drift for form auth helpers (getAuthorizationRequirements / setAuthParams) remains until fix(schemas): allow modelName, setAuthParams, getAuthorizationRequirements in api-module definition #701 merges; docs label that as In review.

Verification

• Compared schema + fathom/hubspot definition.js / package.json / file trees on library next via GitHub API.
• Confirmed skill paths exist on frigg next locally.
• Confirmed frigg validate on next validates app definitions (feat(devtools): frigg validate, and make the app-definition schema match the runtime (ADR-051) #666), not standalone module packages.
• Local markdown→HTML preview of both pages (not GitBook):
  Contribute an API Module preview
  API Module Definition reference preview
• Not done: GitBook hosted preview (no GitBook deploy from this agent).

CI note

Pre-existing red CI on next (MongoMemoryServer / libcrypto) — docs-only PR; do not treat that failure as introduced here.

Out of scope

No changes to support, hosts, OTel, or website/.

_{To show artifacts inline, enable in settings.}

  

---

Note

Low Risk
Documentation-only changes with no runtime, auth, or data-handling code paths affected.

^{Reviewed by Cursor Bugbot for commit 0fa0bb5. Bugbot is set up for automated code reviews on this repo. Configure here.}

[claude]

⚠️ Code review skipped — your organization has no extra usage available to pay for this review.

If your organization's extra usage balance is empty, an organization admin can add extra usage credits at claude.ai/admin-settings/usage. If its monthly spend limit was reached, an admin can raise it on the same page. If neither applies, contact Anthropic support.

Once extra usage is available, someone with write access to this repository can comment @claude review on this pull request to trigger a review.

[netlify]

✅ Deploy Preview for friggframework-org canceled.

Name	Link
🔨 Latest commit	0fa0bb5
🔍 Latest deploy log	https://app.netlify.com/projects/friggframework-org/deploys/6ade4fec5b05e2cf8037eb76

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud