fix(docs): make TypeScript code blocks parseable by sort-imports plugin

[lourou]

Summary

Two code blocks in docs/plans/agent-invite-endpoint-plan.md were bare top-level object literals. prettier-plugin-sort-imports parses every ```typescript block as a TS module to sort imports, and babel rejects these particular blocks as "labeled statement followed by comma" — surfacing as two recurring import sorting aborted due to babel parsing error warnings in prettier --check across CI for any PR touching this tree (noticed on #219 and the IAP branches).

Wrapping the snippets in declarations (const … = z.object({…}) and type Response = …) makes them valid TS, drops the warnings, and keeps the docs readable.

Test plan

• bun format:check → no more babel parsing errors
• CI green on this PR

---

^{Need help on this PR? Tag @codesmith with what you need.}

• Let Codesmith autofix CI failures and bot reviews

Note

Fix TypeScript code blocks in agent invite endpoint plan to be parseable by sort-imports plugin

Updates TypeScript snippets in agent-invite-endpoint-plan.md to use valid, parseable syntax. The request validation example is rewritten as an explicit Zod schema, and the response shape is expressed as a TypeScript union type instead of comment-based object examples.

^{Macroscope summarized 99223e6.}

Summary by CodeRabbit

• Documentation
  • Updated agent invite endpoint documentation with clarified request validation and response structure specifications.

[coderabbitai]

Walkthrough

The plan document for the agent invite endpoint is updated with refined code snippets. The join handler's request validation schema is now explicitly structured as a Zod object defining slug constraints and optional instructions, and the response shape is reformatted as a TypeScript union type with separate success and error branches.

Changes

Agent Join Endpoint Plan Update

Layer / File(s)	Summary
Join handler request validation and response typing docs/plans/agent-invite-endpoint-plan.md	The join handler's documented request body defines a dedicated Zod object schema with slug validation and optional instructions field. The response shape is updated to a TypeScript Response union with distinct success: true and success: false variants, each with their respective fields.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Possibly related PRs

• xmtplabs/convos-backend#170: Creates the initial agent invite endpoint plan document that this PR refines with improved request validation and response type documentation.

Suggested reviewers

• neekolas
• macroscopeapp

Poem

🐰 A plan refined, like carrots arranged just right,
Request validation and responses typed tight,
The join handler's shape now crystal and clear,
Documentation flourishes, the path is here! 📋✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main change: fixing TypeScript code blocks in documentation to be parseable by the sort-imports plugin, which directly addresses the Babel parsing errors mentioned in the PR objectives.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

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

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch louis/fix-lint-md-typescript-blocks

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[claude]

Claude finished @lourou's task —— View job

---

PR Review Complete ✓

Tasks

• Read repository guidelines (CLAUDE.md)
• Review the changed file
• Provide feedback on code quality, bugs, performance, security, and test coverage

---

Review Summary

Verdict: ✅ Approved — This is a clean, well-targeted fix with no issues.

Code Quality & Best Practices ✓

The changes are exemplary:

1. Problem correctly identified: The bare object literals ({ slug: z.string()... } and { success: true... }) were invalid TypeScript modules, causing babel parsing errors in prettier-plugin-sort-imports.

2. Minimal, precise fix:

   • Lines 66-69: Wrapping the zod schema in const requestBody = z.object({...}) makes it valid TS
   • Lines 75-78: Converting the response shape to a proper discriminated union type (type Response = ...) is both more idiomatic and parseable

3. Preserves readability: The documentation remains clear and actually becomes more useful — the first example now shows the proper zod declaration pattern, and the second shows TypeScript's discriminated union syntax.

Potential Bugs or Issues ✓

None. The changes are purely syntactic wrappers that:

• Don't affect the semantic meaning of the documentation
• Make the code blocks valid TypeScript
• Eliminate the CI warnings completely

Performance Considerations ✓

N/A — This is a documentation-only change with zero runtime impact.

Security Concerns ✓

None. Documentation fix only.

Test Coverage ✓

Appropriate testing approach:

• The PR description confirms bun format:check now passes without babel parsing errors
• For a documentation fix, this is the correct test (ensuring the tooling works)
• No code tests needed since no application code changed

Additional Observations

• Commit message: Well-structured with clear explanation of the root cause
• PR description: Excellent — explains the problem, solution, and includes test verification
• Scope: Perfectly minimal — only touches the problematic code blocks

---

Recommendation

Merge when CI is green. This is a textbook example of a focused, well-documented fix.

---

[macroscopeapp]

Approvability

Verdict: Approved

Documentation-only changes that improve TypeScript code block syntax in a planning document. No runtime code is affected.

^{You can customize Macroscope's approvability policy. Learn more.}