Skip to main content

TwentyCRM Integration

Two-way synchronization between TwentyCRM account records and local tool documentation files, enabling seamless management of tool metadata and AI-generated overview notes.

Overview​

The TwentyCRM integration provides:

  • Two-way account sync: Account data syncs between TwentyCRM and local frontmatter
  • One-way note sync: AI-generated overview notes sync from local to TwentyCRM
  • Automatic updates: Account data pulls from TwentyCRM during build
  • Manual sync: Push local changes to TwentyCRM on demand
  • Duplicate prevention: Automatically prevents duplicate notes and noteTarget links

How It Works​

Account Synchronization​

Account records in TwentyCRM are synced with tool documentation files (tools/*.md) using the accountId field in frontmatter as the unique identifier.

Sync Direction:

  • FROM TwentyCRM → Local: Runs automatically during build (sync.js --from-twentycrm)
  • TO TwentyCRM ← Local: Run manually after editing tool files (sync.js --to-twentycrm tools/[name].md)

Note Generation and Sync​

AI-powered overview notes are generated using Google's Gemini API and synced to TwentyCRM as internal documentation.

Workflow:

  1. Generate note: node scripts/sync-tools/generate-note.js tools/[name].md
  2. Review/edit generated note in scripts/sync-tools/generated-notes/[accountId].md
  3. Sync to TwentyCRM: node scripts/sync-tools/sync.js --to-twentycrm tools/[name].md

Note Behavior:

  • Updates existing notes (via PATCH) - no duplicates created
  • Finds notes by title: "Tool Documentation: [tool-name]"
  • Prevents duplicate links: Checks for existing noteTarget links before creating
  • Cleans up duplicates: Removes extra links if multiple exist

Key Features​

1. Note Context Section​

Add a ## Note Context section at the bottom of tool files to guide AI note generation:

## Note Context

**Importance Rating**: Low - This is a convenience tool, not mission-critical.
**Focus Areas for Note**: Emphasize X, clarify Y, note that Z is a future plan not current practice.

This section is used by the AI but does not appear in the generated note.

2. Duplicate Prevention​

The sync script automatically:

  • Finds existing notes by title before creating
  • Updates existing notes instead of creating duplicates
  • Checks for existing noteTarget links before creating
  • Removes duplicate links if multiple exist (keeps 1, deletes extras)

3. AI Note Generation​

Notes are generated using:

  • Gemini API: Google's AI for natural language generation
  • Pacing Agency tone of voice: Partnership-focused, confident but approachable
  • Tool documentation context: Full tool file body used as context
  • Note Context guidance: Explicit instructions from ## Note Context section

File Structure​

Source Files​

  • tools/*.md - Tool documentation with frontmatter and ## Note Context section
  • scripts/sync-tools/sync.js - Main sync script
  • scripts/sync-tools/generate-note.js - AI note generation
  • scripts/sync-tools/generated-notes/{accountId}.md - Generated notes (review before sync)

Documentation​

  • scripts/sync-tools/README.md - Complete system overview
  • scripts/sync-tools/AGENT_WORKFLOW.md - Workflow for improving tools
  • scripts/sync-tools/TOOL_ENRICHMENT_CHECKLIST.md - Step-by-step checklist
  • tools/twentycrm.md - TwentyCRM API documentation

Usage​

For Agents Working on Tools​

See scripts/sync-tools/AGENT_WORKFLOW.md for the complete workflow.

Quick steps:

  1. Improve tool file (tools/[name].md)
  2. Add ## Note Context section at bottom
  3. Generate note: node scripts/sync-tools/generate-note.js tools/[name].md
  4. Review/edit generated note
  5. Sync: node scripts/sync-tools/sync.js --to-twentycrm tools/[name].md

If duplicate noteTarget links exist:

node scripts/sync-tools/cleanup-duplicate-links.js [noteId] [accountId]

The sync script now prevents duplicates automatically, but this utility can clean up existing issues.

Configuration​

Environment Variables​

Create .env file in workspace root:

TWENTYCRM_API_KEY=your-api-key-here
TWENTYCRM_API_BASE=https://pacingagency.com/rest
GEMINI_API_KEY=your-gemini-api-key-here

Dependencies​

Install dependencies for note generation:

cd scripts/sync-tools
npm install

Build Integration​

Automatic (during build):

  • sync.js --from-twentycrm - Pulls account data FROM TwentyCRM
  • sync-tools.cjs - Syncs tools/*.md → docusaurus/docs/tools/
  • sync-notes.cjs - Syncs generated notes → docusaurus/static/notes/

Manual (run when needed):

  • generate-note.js - Generate AI overview notes
  • sync.js --to-twentycrm - Push local changes TO TwentyCRM

Troubleshooting​

Duplicate Notes​

  • The sync script updates existing notes automatically
  • If duplicates exist, delete manually in TwentyCRM first
  • Run cleanup script: node scripts/sync-tools/cleanup-duplicate-links.js <noteId> <accountId>
  • Future syncs will prevent duplicates automatically

API Errors​

  • Check .env file has TWENTYCRM_API_KEY
  • Verify API key is valid and hasn't expired
  • Check note permissions in TwentyCRM

See Also​

  • scripts/sync-tools/README.md - Complete system documentation
  • scripts/sync-tools/AGENT_WORKFLOW.md - Agent workflow guide
  • tools/twentycrm.md - TwentyCRM API reference