docs(everhour): update source docs with sections and custom_fields tables from PR #118989 (#21314)

Co-authored-by: inkeep[bot] <257615677+inkeep[bot]@users.noreply.github.com>

Author: inkeep[bot]

contents/docs/cdp/sources/everhour.md

@@ -9,28 +9,36 @@ availability:
 sourceId: Everhour
 ---
 
-import SourceSetupIntro from "../_snippets/source-setup-intro.mdx"
-import SyncModes from "../_snippets/sync-modes.mdx"
-import TroubleshootingLink from "../_snippets/dw-troubleshooting-link.mdx"
+import SourceSetupIntro from "../\_snippets/source-setup-intro.mdx"
+import SyncModes from "../\_snippets/sync-modes.mdx"
+import TroubleshootingLink from "../\_snippets/dw-troubleshooting-link.mdx"
 
-The Everhour connector syncs your time-tracking data into the PostHog Data warehouse, so you can analyze your time entries and projects alongside your product data.
+[Everhour](https://everhour.com) is a time-tracking, budgeting, and resource-planning tool for teams. This source syncs your Everhour clients, projects, tasks, project sections, project custom fields, team members, time records, invoices, expenses, expense categories, timecards, timesheets, and resource planner assignments, time off types and allocations into the PostHog data warehouse so you can join time-tracking data with your product and revenue data.
 
 ## Prerequisites
 
-You need a paid Everhour plan, as API access is not available on the free tier.
+Using the Everhour API requires a **paid Everhour plan**. You'll need your personal API key, which you can find in your [Everhour profile settings](https://app.everhour.com/#/account/profile) under the API section.
 
 ## Adding a data source
 
 <SourceSetupIntro />
 
-When linking Everhour, you'll need:
+You'll need your Everhour **API key**:
 
-- **API key** – find it in your [Everhour profile settings](https://app.everhour.com/#/account/profile) under the API section.
+1. Sign in to [Everhour](https://app.everhour.com).
+2. Open your [profile settings](https://app.everhour.com/#/account/profile).
+3. Copy the key from the **API** section.
+
+Paste the key into the API key field when connecting the source in PostHog. The key is sent only over the `X-Api-Key` header to `https://api.everhour.com`.
 
 ## Sync modes
 
 <SyncModes />
 
+**Time records** support incremental sync: PostHog uses Everhour's server-side `from`/`to` date window to pull only entries on or after the last synced date.
+
+Every other table syncs as **full refresh**. Clients, projects, users, tasks, sections, custom fields, invoices, expenses, expense categories, timesheets, time off types, and allocations have no server-side change timestamp to filter on. Timecards and assignments do accept a date filter, but it selects rows by the day they cover rather than the day they changed, so it cannot tell PostHog what is new since the last sync.
+
 ## Configuration
 
 <SourceParameters />
@@ -39,9 +47,21 @@ When linking Everhour, you'll need:
 
 <SourceTables />
 
+A few notes:
+
+- **Time values are in seconds.** The `time` field on time records and tasks is a duration in seconds (e.g. `3600` is one hour).
+- **Tasks are fanned out per project.** Each task row carries the parent `project_id` it was fetched under, and the primary key is `(project_id, id)` because a task can belong to more than one project. Sections and custom fields are also fetched per project. Custom field rows carry `project_id` too, and their primary key is `(project_id, id)`.
+- **Integration IDs are prefixed.** Projects and tasks imported from integrations use a prefixed id (e.g. `as:` for Asana, `jira:` for Jira, `tr:` for Trello).
+- **Timecards and time records are different things.** A time record is time logged against a task. A timecard is a clock-in and clock-out for one person on one day. Timecards carry no id of their own, so the table is keyed on `(user, date)`.
+- **Invoice line items are nested.** Each invoice row carries its line items in the `invoiceItems` column rather than in a separate table.
+- **Assignments cover planned work and time off.** The `type` column tells the two apart, and the rows reach into the future because they describe scheduled work.
+- **Timesheets are fetched per person.** Everhour's team-wide timesheet endpoint returns one week at a time, so PostHog reads each member's own timesheet history instead, going back about five years. Each row is one person's week, with its tasks, daily totals, timecards, scheduled time off, and approval history nested inside it.
+- **Lookup tables resolve the ids on other rows.** Expense categories name the `category` on an expense, time off types name the `timeOffType` on an assignment or an allocation, sections name the section a task sits in, and custom fields describe the custom field values on a task.
+- **Allocations are entitlements, not bookings.** A row says how many days off of one type a person has over a period and how many they have used. The time off they actually booked is in assignments.
+
 ## Troubleshooting
 
-- If you see an authentication error, your API key is invalid or has been revoked. Generate a new key in your Everhour profile settings, then reconnect.
-- If you see a permissions error, the key does not have access to this data. Check the key's permissions in Everhour, then reconnect.
+- **Invalid API key** – if the connection fails to validate, regenerate your key in your Everhour profile settings and reconnect. The key requires a paid Everhour plan.
+- **Rate limits** – Everhour rate-limits at roughly 20 requests per 10 seconds per API key. PostHog automatically honors the `Retry-After` header and backs off, so large initial syncs of time records may take a while to complete.
 
 <TroubleshootingLink />