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

Cleanup Duplicate Links

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

Bootstrapping Tool Metadata from a CSV Export

When setting up the tool sync system for the first time (or re-importing after a TwentyCRM data migration), you can bootstrap frontmatter into all tools/*.md files from a TwentyCRM CSV export rather than syncing each file manually via the API.

This is a one-time setup workflow - once all tool files have a valid accountId in their frontmatter, the API-based sync (sync.js) handles everything going forward.

When to use this

• Initial setup: your TwentyCRM has all accounts but the tool docs have no accountId frontmatter yet
• After a data migration where account IDs changed
• When creating a large batch of new tool docs from existing TwentyCRM data

Scripts involved

These scripts live in scripts/ at the repo root and are not part of the automated build pipeline.

Script	Purpose
match-csv-to-tools.js	Parses the TwentyCRM CSV export and matches each account to an existing tools/*.md file by name. Produces a JSON mapping file.
preview-frontmatter-example.js	Shows a preview of the frontmatter that will be written, using Webflow as an example. Useful to verify the mapping before applying.
add-frontmatter-to-tools.js	Reads the JSON mapping and writes frontmatter into each matched tool file. Creates timestamped backups in scripts/resources/tool-backups/ before modifying anything.

Step-by-step

1. Export accounts from TwentyCRM

In TwentyCRM, export the Accounts table as CSV. Save it to ~/Downloads/account.csv (the default path expected by the script).

The expected CSV columns are: Tool Name, Category, Monthly Cost / Amount, Monthly Cost / Currency, Annual Cost / Amount, Annual Cost / Currency, Renewal Date, Account Type, Access/Login Link / Link URL, Access/Login Link / Link Label, More Information, Account Owner Id.

2. Match CSV accounts to tool files

node scripts/match-csv-to-tools.js

Outputs:

• scripts/resources/tool-csv-mapping.json - matched tools (input to next step)
• scripts/resources/unmatched-tools.json - accounts with no matching tools/*.md file (create these manually)

The script normalises names for fuzzy matching and has hardcoded overrides for abbreviations like Google Tag Manager → gtm.

3. Preview what will be written

node scripts/preview-frontmatter-example.js

Prints the frontmatter format using Webflow as a sample. Lets you verify the field mapping before touching any files.

4. Dry run

node scripts/add-frontmatter-to-tools.js --dry-run

Lists every file that would be modified without touching anything.

5. Apply

node scripts/add-frontmatter-to-tools.js

Writes frontmatter to each matched tool file and saves .backup copies to scripts/resources/tool-backups/.

6. Add accountIds to unmatched tools

For any tool in unmatched-tools.json, either create the tools/*.md file and re-run the workflow, or manually copy the accountId from TwentyCRM into the frontmatter.

7. Validate

node scripts/sync-tools/sync.js --validate

Confirms every tool file has a valid accountId that exists in TwentyCRM.

After bootstrapping

Once all tools have frontmatter with a valid accountId, switch to the normal API-based workflow for any further changes:

# Pull latest account data from TwentyCRM
node scripts/sync-tools/sync.js --from-twentycrm

# Push a tool doc back to TwentyCRM after editing
node scripts/sync-tools/sync.js --to-twentycrm tools/webflow.md

The CSV bootstrap scripts are no longer needed once the initial sync is complete.

---

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

Duplicate Links

• 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

Related Features

• Tool Categorization System - Automated tool organization
• Tool Metadata - Structured tool information
• Tools Overview - Comprehensive tools documentation

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