setup

Purpose

Collect and save the Notion database IDs for the 6 CRM databases to .claude/settings.json in the current project directory. These IDs are required by all notion-crm-helper skills. Once saved, the config persists for the project and can only be updated by running this setup skill again.

The expected format is documented in skills/setup/resources/settings.json inside the notion-crm-helper plugin.

Step 1 — Check for Existing Config

Read the file .claude/settings.json from the current project directory. Parse it as JSON and check for the presence of NOTION_CRM_CONTACTS_DB_ID in the env object.

• If the project directory does not have a .claude/settings.json file, or the file exists but has no env key, proceed directly to Step 2.

• If the file exists and NOTION_CRM_CONTACTS_DB_ID is set in env, immediately write the config to ~/.claude/notion-crm-helper.local.md (Step 1a below), then show the current config and ask the user if they want to update.

Step 1a — Write Local Config File and Check Schema (runs whenever settings.json is found)

Using the values read from .claude/settings.json, write the file ~/.claude/notion-crm-helper.local.md with the following YAML frontmatter format. Map the env keys to lowercase snake_case property names (drop the NOTION_CRM_ prefix):

---
contacts_db_id: "[NOTION_CRM_CONTACTS_DB_ID]"
accounts_db_id: "[NOTION_CRM_ACCOUNTS_DB_ID]"
opportunities_db_id: "[NOTION_CRM_OPPORTUNITIES_DB_ID]"
lists_db_id: "[NOTION_CRM_LISTS_DB_ID]"
templates_db_id: "[NOTION_CRM_TEMPLATES_DB_ID]"
activities_db_id: "[NOTION_CRM_ACTIVITIES_DB_ID]"
crm_parent_page_id: "[NOTION_CRM_PARENT_PAGE_ID]"
---

Leave any value as "" if the corresponding env key is empty or missing. Use the Write tool to save the file. Do not tell the user about this step — just do it silently.

Also silently check for .claude/crm-schema.json:

• If the file exists, read it and extract last_validated. Compute how many days ago that timestamp was. Note this for display (do not warn yet — just prepare to show it in the config summary below).
• If the file does not exist, note "Schema not generated" for display.

After writing ~/.claude/notion-crm-helper.local.md, show the current config:

Your current Notion CRM configuration:

- Contacts DB:      [NOTION_CRM_CONTACTS_DB_ID]
- Accounts DB:      [NOTION_CRM_ACCOUNTS_DB_ID or "Not set"]
- Opportunities DB: [NOTION_CRM_OPPORTUNITIES_DB_ID]
- Lists DB:         [NOTION_CRM_LISTS_DB_ID]
- Templates DB:     [NOTION_CRM_TEMPLATES_DB_ID]
- Activities DB:    [NOTION_CRM_ACTIVITIES_DB_ID or "Not set"] (optional)
- Parent Page:      [NOTION_CRM_PARENT_PAGE_ID or "Not set"]

Schema: [N days old / "Schema not generated — re-run setup to enable accurate property matching"]

Then ask: "Would you like to update your configuration, or keep the current one?"

• If the user wants to keep it, end the skill: "Your configuration is unchanged. All notion-crm-helper skills will continue using your saved database IDs."

• If the user wants to update, proceed to Step 2.

• If no project folder is loaded (no .claude/ directory is accessible), stop and tell the user:

  No project folder detected. Please open a project directory in Claude Code first — configuration is saved to .claude/settings.json in your project folder.

Step 2 — Verify Notion Connection

Use notion-search with a broad query (e.g., "CRM") to confirm the Notion connection is active.

• If it fails with an auth error, tell the user:

  The Notion connector doesn't appear to be connected. In Claude Code, check that the notion MCP server is authorized. You may need to re-connect Notion via the MCP settings.

  Do not proceed until the connection is confirmed working.

Step 3 — Get the CRM Parent Page

Ask the user:

What is the URL of your Notion CRM parent page? This is the page where your 6 CRM databases live (or will be created).

Extract the page ID from the URL — the 32-character hex string at the end (remove hyphens if present):

• https://www.notion.so/My-CRM-83a0ac85cdd3464c92083b1336f7bfe7 → 83a0ac85cdd3464c92083b1336f7bfe7
• https://www.notion.so/83a0ac85-cdd3-464c-9208-3b1336f7bfe7 → 83a0ac85cdd3464c92083b1336f7bfe7

Store this as the value for NOTION_CRM_PARENT_PAGE_ID.

Step 4 — Discover Database IDs

Use notion-search to find each of the 6 CRM databases by name. For each result, extract the database ID from the returned object.

Search for:

1. "Contacts" → store ID as NOTION_CRM_CONTACTS_DB_ID
2. "Accounts" → store ID as NOTION_CRM_ACCOUNTS_DB_ID
3. "Opportunities" → store ID as NOTION_CRM_OPPORTUNITIES_DB_ID
4. "Lists" → store ID as NOTION_CRM_LISTS_DB_ID
5. "Templates" → store ID as NOTION_CRM_TEMPLATES_DB_ID
6. "Activities" → store ID as NOTION_CRM_ACTIVITIES_DB_ID (optional — if not found, skip without flagging as missing)

For each database found, confirm with the user: "Found Contacts database (ID: abc123...). Is this the right one?"

If the user says no, ask them to paste the direct Notion database URL for that database and extract the ID manually.

If any required databases (Contacts, Accounts, Opportunities, Lists, Templates) are not found, note them as missing and tell the user:

The following databases were not found: [names]. Please paste their Notion URLs now, or create them manually in Notion and re-run setup.

If Activities is not found, note it as optional:

Activities database not found — this is optional. Activity logging won't be available until it's configured.

For each missing required database, ask the user if they want to:

• Paste the database URL now (to set the ID)
• Leave it blank for now (the corresponding skills won't work until it's set)

Step 4.5 — Introspect Database Schemas

For each database ID confirmed in Step 4, call notion-fetch with that database ID to retrieve the full database object. Do this silently — do not report progress to the user. For each database, extract:

1. collection_id: Look for a <data-source url="collection://..."> tag in the notion-fetch response. Extract the full collection://... URL and store it as collection_id for that database.

2. Properties: For each property in the database's property schema, record:

   • Display name (the key)
   • Internal ID (the short opaque Notion-internal ID, e.g. eDptYQ — NOT a UUID; use verbatim)
   • Type (title, rich_text, select, multi_select, number, date, email, phone_number, url, relation, checkbox, etc.)
   • For select and multi_select types: the exact option strings with all emoji preserved (e.g., "🔥 Hot", "❄️ Cold")

3. select_option_aliases: For each select or multi_select property, build an alias map. For each option string:

   • Strip all leading characters that are emoji (Unicode characters in ranges U+1F300 and above, or Unicode Misc Symbols U+2600–U+26FF) and trim any leading/trailing whitespace from the result
   • If the stripped alias differs from the original option string, add alias → original_value to the alias map for that property
   • Example: "🔥 Hot" → stripped alias "Hot" → add "Hot": "🔥 Hot" to the map
   • Example: "Champion" → stripped alias "Champion" → same as original, skip (no alias needed)

Hold all introspected data in memory — it will be written in Step 6c. If notion-fetch fails for a database, skip it without blocking the user (the schema for that database will be empty).

Step 5 — Confirm Before Saving

Show the collected values to the user for confirmation before writing:

Ready to save your Notion CRM configuration:

- Contacts DB:      [NOTION_CRM_CONTACTS_DB_ID or "Not set"]
- Accounts DB:      [NOTION_CRM_ACCOUNTS_DB_ID or "Not set"]
- Opportunities DB: [NOTION_CRM_OPPORTUNITIES_DB_ID or "Not set"]
- Lists DB:         [NOTION_CRM_LISTS_DB_ID or "Not set"]
- Templates DB:     [NOTION_CRM_TEMPLATES_DB_ID or "Not set"]
- Activities DB:    [NOTION_CRM_ACTIVITIES_DB_ID or "Not set"] (optional)
- Parent Page:      [NOTION_CRM_PARENT_PAGE_ID or "Not set"]

Save this configuration?

If the user confirms, proceed to Step 6. If they want changes, return to Step 4 for the specific database(s) they want to change.

Step 6 — Save the Configuration

Step 6a — Write the Session Config (always)

Write the confirmed values to ~/.claude/notion-crm-helper.local.md using the YAML frontmatter format from Step 1a. Do this silently with the Write tool — do not mention it to the user.

Leave any value as "" if the user did not provide it.

Step 6b — Offer to Save a Settings File for Future Setup

After writing the local config, ask the user:

Would you like to save a settings.json file for quicker setup next time? This file can be placed in your project's .claude/ folder so the plugin loads your database IDs automatically on future runs.

• If the user says no, skip to Step 7.
• If the user says yes, construct the settings.json content and display it as a code block artifact so the user can copy and save it themselves:

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "env": {
    "NOTION_CRM_CONTACTS_DB_ID": "[CONTACTS_DB_ID]",
    "NOTION_CRM_ACCOUNTS_DB_ID": "[ACCOUNTS_DB_ID]",
    "NOTION_CRM_OPPORTUNITIES_DB_ID": "[OPPORTUNITIES_DB_ID]",
    "NOTION_CRM_LISTS_DB_ID": "[LISTS_DB_ID]",
    "NOTION_CRM_TEMPLATES_DB_ID": "[TEMPLATES_DB_ID]",
    "NOTION_CRM_ACTIVITIES_DB_ID": "[ACTIVITIES_DB_ID]",
    "NOTION_CRM_PARENT_PAGE_ID": "[CRM_PARENT_PAGE_ID]"
  }
}

Tell the user:

Save this as .claude/settings.json in your project folder. Next time you run setup, it will be detected automatically and your configuration will load instantly.

Leave any IDs as empty strings "" if the user did not provide them.

Step 6c — Write Schema File (always, silently)

Using the data collected in Step 4.5, construct a crm-schema.json object and write it to .claude/crm-schema.json using the Write tool. Do not mention this step to the user — do it silently. If the Write tool fails, warn the user: "Note: Unable to write the schema file to .claude/crm-schema.json. Property matching may be less accurate." — but do NOT block setup completion.

The schema object structure:

{
  "version": "1.0.0",
  "generated_by": "notion-crm-helper:setup",
  "last_updated": "<current ISO 8601 timestamp>",
  "last_validated": "<current ISO 8601 timestamp>",
  "validation_config": { "max_stale_days": 7, "auto_heal": true },
  "important_format_notes": {
    "page_id_format": "Always use UUID format with dashes (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)",
    "relation_format": "Relations require array of {page_id: '<uuid>'}",
    "select_values": "Always use exact string from select_option_aliases — never guess",
    "database_vs_collection_ids": {
      "use_database_id_for": ["notion-create-pages parent", "notion-fetch", "notion-search"],
      "use_collection_id_for": ["notion-update-data-source"]
    }
  },
  "property_aliases": {
    "Contact Name": ["Name", "Full Name", "Contact"],
    "Contact Email": ["Email", "Email Address"]
  },
  "select_option_aliases": {
    "contacts": {
      "<PropertyName>": { "<alias>": "<actual_value_with_emoji>", ... },
      ...
    },
    "accounts": { ... },
    "opportunities": { ... },
    "lists": { ... },
    "templates": { ... },
    "activities": { ... }
  },
  "database_name_mappings": {
    "contacts": ["Contacts", "Contact Database"],
    "accounts": ["Accounts", "Companies"],
    "opportunities": ["Opportunities", "Pipeline"],
    "lists": ["Lists"],
    "templates": ["Templates"],
    "activities": ["Activities"]
  },
  "databases": {
    "contacts": {
      "id": "<uuid from config>",
      "collection_id": "<collection:// url extracted from notion-fetch response>",
      "name": "<actual Notion database name>",
      "properties": {
        "<PropertyDisplayName>": {
          "id": "<short Notion-internal property ID — NOT a UUID>",
          "type": "<property type>",
          "options": ["<exact option string with emoji>", ...],
          "required": true
        },
        ...
      }
    },
    "accounts": { ... },
    "opportunities": { ... },
    "lists": { ... },
    "templates": { ... },
    "activities": { ... }
  },
  "relationships": {
    "contact_to_account": "Company on Contacts is a relation to Accounts — use page_id format",
    "contact_to_opportunity": "Contacts linked via Buying Committee/Champion properties",
    "opportunity_to_account": "Company on Opportunities is a relation to Accounts — use page_id format"
  }
}

Include "options" only for select and multi_select property types. Omit it for all other types. Include "required": true only for the title property of each database.

Step 7 — Confirm Success

Confirm to the user:

Notion CRM configuration saved for this session.

All notion-crm-helper skills will now use your saved database IDs automatically.
Schema file saved: `.claude/crm-schema.json`

Next steps:
- /notion-crm-helper:validate-schema — verify all databases are reachable
- /notion-crm-helper:crm-helper — start managing contacts, pipeline, and activities

To update your configuration in the future, run /notion-crm-helper:setup again.

Error Handling

• If the Write tool fails, tell the user: "Unable to save the configuration to .claude/settings.json. Please check that your project's .claude/ directory exists and is writable. Make sure you have a project folder open in Claude Code."
• Never save a partial configuration without warning the user — if NOTION_CRM_CONTACTS_DB_ID is blank, note that contact and list operations in /notion-crm-helper:crm-helper will not work until it is set. NOTION_CRM_ACTIVITIES_DB_ID is optional and may be left blank without blocking setup.
• If notion-search returns multiple databases with the same name, show the user all matches with their IDs and ask them to confirm which one to use.