docs: Filters-as-code + Webhooks guides

[wavyx]

The two remaining low-priority narrative guides from v0.22. guides/filters.mdx (create/update/helpers/export, conditions JSON with numeric field_id, export round-trip, filter ids on list/bulk) and automation/webhooks.mdx (webhook create/delete/list + webhook listen tunnel/basic-auth/orphan-cleanup and --synthetic). Flags verified against src/; both wired into the sidebar; Astro build green.

https://claude.ai/code/session_018dRMUUj9vpKp3tqKQFsvE9

Greptile Summary

Adds two new narrative guides (guides/filters.mdx and automation/webhooks.mdx) and wires them into the Starlight sidebar. All flags, exit codes, and behavioral claims were cross-checked against the CLI source in src/commands/filter/ and src/commands/webhook/.

• Filters guide (guides/filters.mdx): covers filter create/update/helpers/export, the two-level conditions shape, numeric field_id caveats, and the export round-trip — all accurate against source.
• Webhooks guide (automation/webhooks.mdx): covers CRUD, webhook listen tunnel mode (basic-auth security, orphan cleanup), and --synthetic polling mode — accurate, with one minor omission: the --interval flag accepts milliseconds but the guide only states the default in seconds without naming the unit.

Confidence Score: 4/5

Safe to merge — documentation-only changes with no runtime impact.

Both guides are accurate against the CLI source: flags, exit codes, the conditions shape, the basic-auth rejection logic, orphan cleanup, and the synthetic watermark are all verified. The one gap is that the webhooks guide describes --interval with a seconds-based default but never tells readers the value they pass is in milliseconds, which could cause unintended near-continuous polling for anyone who follows the natural pattern of passing a plain integer.

The --interval unit omission in automation/webhooks.mdx is the only item worth revisiting before merge.

Important Files Changed

Filename	Overview
website/astro.config.mjs	Adds two sidebar entries — guides/filters and automation/webhooks — wired to their newly-created MDX files; positions are correct within each section.
website/src/content/docs/automation/webhooks.mdx	New webhooks guide covering CRUD, webhook listen tunnel/synthetic modes, and orphan cleanup. Flags, exit codes, and security model verified against source. Minor: --interval unit (milliseconds) not stated in the prose.
website/src/content/docs/guides/filters.mdx	New filters-as-code guide covering create/update/helpers/export, conditions shape, export round-trip, and filter-id usage in list/bulk. All commands, flags, exit codes, and cautions verified against source; content is accurate.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
    participant User
    participant pdcli
    participant Pipedrive
    participant Tunnel
    participant App

    Note over User,App: Tunnel mode (--url)
    User->>pdcli: webhook listen --url https://tunnel --forward-to http://localhost:3000
    pdcli->>Pipedrive: POST /api/v1/webhooks (catch-all, basic-auth creds)
    Pipedrive-->>pdcli: webhookId
    Pipedrive->>Tunnel: POST event payload (with basic-auth header)
    Tunnel->>pdcli: forwards POST to :port
    pdcli->>pdcli: verify Authorization header (401 if mismatch)
    pdcli->>User: print delivery line
    pdcli->>App: POST raw payload (--forward-to)
    User->>pdcli: Ctrl-C (SIGINT)
    pdcli->>Pipedrive: "DELETE /api/v1/webhooks/{id}"

    Note over User,App: Synthetic mode (--synthetic)
    User->>pdcli: webhook listen --synthetic --since 15m
    loop every --interval ms
        pdcli->>Pipedrive: GET /api/v2/deals,persons,… (updated_since watermark)
        Pipedrive-->>pdcli: changed records
        pdcli->>User: "emit {event, meta, current, previous} envelope"
        pdcli->>App: POST envelope (--forward-to)
        pdcli->>pdcli: advance watermark
    end

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
    participant User
    participant pdcli
    participant Pipedrive
    participant Tunnel
    participant App

    Note over User,App: Tunnel mode (--url)
    User->>pdcli: webhook listen --url https://tunnel --forward-to http://localhost:3000
    pdcli->>Pipedrive: POST /api/v1/webhooks (catch-all, basic-auth creds)
    Pipedrive-->>pdcli: webhookId
    Pipedrive->>Tunnel: POST event payload (with basic-auth header)
    Tunnel->>pdcli: forwards POST to :port
    pdcli->>pdcli: verify Authorization header (401 if mismatch)
    pdcli->>User: print delivery line
    pdcli->>App: POST raw payload (--forward-to)
    User->>pdcli: Ctrl-C (SIGINT)
    pdcli->>Pipedrive: "DELETE /api/v1/webhooks/{id}"

    Note over User,App: Synthetic mode (--synthetic)
    User->>pdcli: webhook listen --synthetic --since 15m
    loop every --interval ms
        pdcli->>Pipedrive: GET /api/v2/deals,persons,… (updated_since watermark)
        Pipedrive-->>pdcli: changed records
        pdcli->>User: "emit {event, meta, current, previous} envelope"
        pdcli->>App: POST envelope (--forward-to)
        pdcli->>pdcli: advance watermark
    end

Loading

_{Reviews (1): Last reviewed commit: "docs: add Filters-as-code and Webhooks g..." | Re-trigger Greptile}

Greptile also left 1 inline comment on this PR.

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[greptile-apps]

--interval unit not stated in guide

The guide says "--interval sets the gap between poll cycles (default 10s)" without mentioning that the value is in milliseconds. A reader who wants a 60-second interval will naturally try --interval 60 and instead get 60 ms polling (near-continuous). The CLI flag is defined as Flags.integer({ description: 'Milliseconds between synthetic poll cycles', default: 10_000 }) — the --help output shows the unit, but the guide should surface it too so examples and prose are self-contained.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!