chore: Add AGENTS.md file for sync-service

[robacourt]

This PR adds a AGENTS.md file for the sync-service. At the moment it's very small, but it serves as a starting point to add to as we discover issues to do with the agents not having the right context.

Summary by CodeRabbit

• Documentation
  • Added comprehensive documentation for the Electric Sync Service, describing service scope and goals, architecture and subsystems, development workflows and commands, testing guidance, project structure, environment configuration, cross-package APIs, and security and operational guidance.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds a new documentation file for the Electric Sync Service (Elixir) detailing scope, goals, related components, major subsystems, data flow, development commands, project layout, environment/dev settings, testing guidance, boundaries, cross-package APIs, and security/ops notes.

Changes

Cohort / File(s)	Summary
Documentation packages/sync-service/AGENTS.md	New file (+112 lines): Comprehensive documentation for the Electric Sync Service covering scope, goals, component relationships, subsystems, workflows, development commands, project map, environment and dev settings, testing guidance, boundaries, cross-package APIs, and security/ops notes.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

Poem

🐇 I hopped through docs with ink and cheer,
A sync of thoughts now crystal clear.
No code was touched, just maps and lights,
For devs to read on quiet nights.
🥕 Hooray for notes that guide the way!

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'chore: Add AGENTS.md file for sync-service' accurately describes the main change: adding documentation for the sync-service. It's specific, concise, and clearly reflects the primary modification in the changeset.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

📜 Recent review details

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 372a00d and ad0a693.

📒 Files selected for processing (1)

• packages/sync-service/AGENTS.md

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)

• GitHub Check: Run Lux integration tests

🔇 Additional comments (1)

packages/sync-service/AGENTS.md (1)

1-112: Looks good—clear, scoped, and actionable guidance.

The doc is concise, well-structured, and provides practical guidance for agents without overreaching scope.

_{✏️ Tip: You can disable this entire section by setting review_details to false in your review settings.}

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@packages/sync-service/AGENTS.md`:
- Around line 89-93: Add the missing ignore patterns to the sync-service package
.gitignore: open the packages/sync-service/.gitignore and append the two lines
"/log/" and "node_modules/" so the package-level rules match the Boundaries
documentation; ensure they are on their own lines and saved to commit.

📜 Review details

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 6b7b453 and 372a00d.

📒 Files selected for processing (1)

• packages/sync-service/AGENTS.md

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (6)

• GitHub Check: Build and typecheck packages/start
• GitHub Check: Build and typecheck packages/typescript-client
• GitHub Check: Build and typecheck packages/experimental
• GitHub Check: Build and typecheck packages/react-hooks
• GitHub Check: ensure_sync_service_image / build_image
• GitHub Check: Run Lux integration tests

🔇 Additional comments (8)

packages/sync-service/AGENTS.md (8)

8-12: Clear service description.

The description accurately conveys the core purpose and scope of the Electric Sync Service.

---

81-87: Good Elixir testing pattern example.

The code example demonstrates proper pattern matching in assertions, which is idiomatic Elixir. The syntax is correct and the guidance is valuable for maintaining consistent test style.

---

6-6: The referenced ../../AGENTS.md file exists at the repository root.

---

14-28: All referenced subsystem directories exist and the documentation is accurate.

---

54-58: All services and ports documented in dev/docker-compose.yml are correctly configured: postgres (54321), postgres2 (54322), pgbouncer (65432), and nginx (3002) all exist with accurate port mappings as stated.

---

42-52: All project map paths are correct and exist. Verification confirms all 8 directories and files referenced in the project map (lib/electric/plug/, lib/electric/replication/, lib/electric/shapes/, lib/electric/shape_cache/, lib/electric/telemetry/, lib/pg_interop/, config/runtime.exs, and dev/) are present and accurately listed.

---

69-75: All referenced test paths exist and are correctly documented.

---

95-99: Security guidance is accurate and well-implemented.

The environment variables are properly validated: ELECTRIC_INSECURE and ELECTRIC_SECRET are mutually exclusive, with runtime errors enforced in lib/electric/config.ex. The distinction between dev and prod configurations is correct, and the warning about lib/electric/plug/* changes is appropriate given these modules handle public HTTP API endpoints.

_{✏️ Tip: You can disable this entire section by setting review_details to false in your review settings.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 87.36%. Comparing base (5a767e6) to head (ad0a693).
⚠️ Report is 11 commits behind head on main.
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3735      +/-   ##
==========================================
+ Coverage   84.01%   87.36%   +3.35%     
==========================================
  Files          44       23      -21     
  Lines        2834     2011     -823     
  Branches      534      528       -6     
==========================================
- Hits         2381     1757     -624     
+ Misses        451      252     -199     
  Partials        2        2              

Flag	Coverage Δ
elixir	?
elixir-client	?
packages/experimental	87.73% <ø> (ø)
packages/react-hooks	86.48% <ø> (ø)
packages/start	82.83% <ø> (ø)
packages/typescript-client	93.47% <ø> (ø)
packages/y-electric	56.05% <ø> (ø)
typescript	87.36% <ø> (ø)
unit-tests	87.36% <ø> (+3.35%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[alco]

LGTM!