docs(intercom): document the read-only Intercom datasource for the Ruby agent

[christophebrun-forest]

Documents the Intercom datasource of the Ruby agent (gem forest_admin_datasource_intercom), built on the branch feat/datasource-intercom of agent-ruby.

Draft: the datasource itself is not released yet.

What this adds

• get-started/connect/data-sources/intercom.mdx — the page, modelled on the Pylon one, which is the most recent precedent in this repo.
• Three hook-ups: the docs.json nav, the "Available datasources" list on the data-sources overview, and an Intercom <Card> in the integrations catalogue under Support & ticketing.

The framing

The read-only scope is stated up front as a deliberate choice, not as a gap, with its counterpart right next to it: the datasource refuses rather than approximates — where Intercom's API has no equivalent for what Forest asks, it answers a 400 naming what to change instead of a page that looks filtered, sorted or counted and is not. What comes after this version (writes, actions, notes/tags/segments, bounded group-by) is a table at the end rather than a caveat sprinkled throughout.

The page covers installation, configuration, token permissions, the nine collections and their three pagination tiers (cursor / offset / read whole), relations and what each one costs, the conversation and ticket threads, custom attributes, the per-endpoint filter tables, sorting, pagination, aggregations, rate limits, privacy, boot-time introspection, errors and logging.

On accuracy

The package README is excellent and is the base, but it was cross-checked against the code rather than transcribed:

• Caps carry their real figures rather than a link to the constant, which does not travel to a public doc: MAX_RELATION_READS 100, MAX_COLLECTED_PAGES 10, MAX_PAGES 50 / MAX_RECORDS 7 500, MAX_PER_PAGE 150 (25 on tickets), MAX_TIMELINE_READS 10, MAX_ID_READS 25, DEFAULT_MAX_WAIT 12s.
• The "18 of 89 measured" ratio is the one the package asserts against its own search-field table (fields + refused rows — a naive count of the fields alone gives 62/8).
• The filterable-columns tables are the ones that spec asserts against filterable_columns, so they cannot drift from the code.
• Two claims corrected against what the README implied: no raise is tied to sorting (an unhonoured order is logged, never refused), and a count can be refused should Intercom ever answer a listing without a total_count. Both are reflected in the page.

mint broken-links passes, and every in-page anchor resolves to a heading.

Worth a look in agent-ruby, not here

The package README still opens with "This is lot 1: read only", which is now stale — contacts and companies (lot 4) are in. The public page carries no lot numbering, so nothing here depends on it, but it may deserve a fix on that side.

🤖 Generated with Claude Code

Note

Add documentation for the read-only Intercom datasource

• Adds a new MDX page covering installation, configuration, nine read-only collections, relationships, timelines, filtering, pagination, rate limiting, and privacy handling for the Ruby-only Intercom datasource
• Registers the new route in docs.json and adds Intercom entries to the data-source overview and integrations overview pages

📊 Macroscope summarized 7427383. 4 files reviewed, 5 issues evaluated, 4 issues filtered, 1 comment posted

🗂️ Filtered Issues

get-started/connect/data-sources/intercom.mdx — 1 comment posted, 5 evaluated, 4 filtered

• line 13: The links at lines 13 and 360 target #what-is-not-here-yet, but this added page contains no heading with that slug. Clicking either link lands nowhere, so readers cannot reach the promised scope details. [ Out of scope (triage) ]
• line 460: The privacy/logging description says logs carry Intercom's request id, but the connector never writes a request_id to its logger. Client#error_message only appends it to an APIError message for an error response; all direct warning logs contain endpoint names, counts, or HTTP status only. Operators following this documentation will not have the request id promised for Intercom support investigations. [ Out of scope (post-validation triage) ]
• line 467: The claim that construction performs exactly four reads is false when any boot-time introspection is paginated. All three introspectors call Client#fetch_all, whose collect_pages follows next_cursor for up to MAX_COLLECTED_PAGES; such a workspace makes each affected endpoint issue additional boot requests. This also contradicts the page's own later warning about those endpoints being paginated. [ Out of scope (post-validation triage) ]
• line 500: APIError#body is not always parsed as the table states: Client#parse_body rescues JSON::ParserError and returns the original response string. A caller rescuing APIError after an Intercom error with malformed/non-JSON content will receive raw text rather than the documented parsed body. [ Out of scope (post-validation triage) ]

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
forest	🟢 Ready	View Preview	Sep 11, 2026, 8:25 AM

💡 Tip: Enable Automations to automatically generate PRs for you.

[macroscopeapp]

🟢 Low data-sources/intercom.mdx:518

The source link returns GitHub's missing-path page because packages/forest_admin_datasource_intercom is not present on agent-ruby/main; readers cannot access the promised connector source. Point the link at the feat/datasource-intercom branch where the datasource exists.

Suggested change

	[`forest_admin_datasource_intercom`](https://github.com/ForestAdmin/agent-ruby/tree/main/packages/forest_admin_datasource_intercom)
	[`forest_admin_datasource_intercom`](https://github.com/ForestAdmin/agent-ruby/tree/feat/datasource-intercom/packages/forest_admin_datasource_intercom)

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file @get-started/connect/data-sources/intercom.mdx around line 518:

The source link returns GitHub's missing-path page because `packages/forest_admin_datasource_intercom` is not present on `agent-ruby/main`; readers cannot access the promised connector source. Point the link at the `feat/datasource-intercom` branch where the datasource exists.