docs: cleanup and reorganize documentation

[shuhuiluo]

Simplified and reorganized all documentation for better clarity:

README.md:

• Simplified environment variables (show only required)
• Merged duplicate commands sections
• Simplified GitHub App Setup with CONTRIBUTING.md reference
• Reorganized Future Enhancements into categories

CONTRIBUTING.md (new):

• Developer setup guide
• Environment variables reference (tables)
• GitHub App setup instructions
• Database management
• Project structure
• Deployment checklist

.env.sample:

• Added missing variables (OAUTH_REDIRECT_URL, DRIZZLE_MIGRATIONS_PATH)
• Fixed variable names to match code

AGENTS.md:

• Condensed from 1396 lines to 209 lines
• Essential info only

Result: Clear separation between user (README) and developer (CONTRIBUTING) docs, eliminating duplication.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation

  • New CONTRIBUTING.md guide added with development setup, database management, and deployment practices.
  • README reorganized: shifted from granular command syntax to higher-level workflows; added delivery modes guidance and Future Enhancements section.
  • AGENTS.md streamlined with focus on stateless event processing and canonical interaction patterns.

• Chores

  • Added OAUTH_REDIRECT_URL and DRIZZLE_MIGRATIONS_PATH environment variables.
  • Updated OAuth flow documentation to reflect unified subscription and webhook/polling delivery logic.

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

[coderabbitai]

Warning

Rate limit exceeded

@shuhuiluo has exceeded the limit for the number of commits or files that can be reviewed per hour. Please wait 6 minutes and 32 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

📥 Commits

Reviewing files that changed from the base of the PR and between 6c49bf6 and 52a8d89.

📒 Files selected for processing (1)

• CONTRIBUTING.md (1 hunks)

Walkthrough

This pull request updates configuration files and documentation across the project. It introduces two new environment variables (OAUTH_REDIRECT_URL and DRIZZLE_MIGRATIONS_PATH) in .env.sample, creates a new CONTRIBUTING.md guide detailing development setup and workflows, and significantly rewrites existing documentation files (AGENTS.md, GITHUB_APP_IMPLEMENTATION_PLAN.md, and README.md) to emphasize conciseness, stateless architecture, and unified OAuth flows. The documentation shifts focus from detailed command references and multi-step workflows toward streamlined examples and higher-level usage patterns. CLAUDE.md receives a minor formatting adjustment.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

• GITHUB_APP_IMPLEMENTATION_PLAN.md: Substantial architectural changes to the OAuth subscription flow, including new delivery-mode logic (webhook vs. polling), state management in OAuth callbacks, and updated user-facing success messaging—requires careful verification of the new flow correctness
• README.md: Significant reorganization and consolidation of documentation structure; sections shifted from granular command syntax to higher-level workflows; verify that removed details are adequately covered elsewhere
• AGENTS.md: Major rewrite affecting handler patterns, API terminology (bot.botId → bot.appAddress), and example consolidation; ensure consistency with broader codebase patterns
• CONTRIBUTING.md: New file with comprehensive setup and workflow guidance; verify completeness and accuracy of environment setup, database, and deployment instructions

Possibly related PRs

• docs: add GitHub App implementation plan #25: Contains overlapping edits to GITHUB_APP_IMPLEMENTATION_PLAN.md focused on reworking the subscription/OAuth callback flow and delivery-mode logic
• docs: add subscription system to implementation plan #27: Modifies the GitHub App implementation plan with unified OAuth/subscription flow and delivery-mode logic (polling vs. webhooks/installation)

Pre-merge checks and finishing touches

✅ 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 'docs: cleanup and reorganize documentation' directly matches the changeset, which focuses on simplifying and reorganizing multiple documentation files (README.md, CONTRIBUTING.md, AGENTS.md, etc.) and removing duplication.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

---

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.}

[coderabbitai]

Actionable comments posted: 1

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between d9d1a59 and 6c49bf6.

📒 Files selected for processing (6)

• .env.sample (1 hunks)
• AGENTS.md (1 hunks)
• CLAUDE.md (1 hunks)
• CONTRIBUTING.md (1 hunks)
• GITHUB_APP_IMPLEMENTATION_PLAN.md (2 hunks)
• README.md (4 hunks)

🧰 Additional context used

🪛 LanguageTool

GITHUB_APP_IMPLEMENTATION_PLAN.md

[uncategorized] ~243-~243: The official name of this software platform is spelled with a capital “H”.
Context: ...ntation #### 1. Slash Command Handler (/github subscribe owner/repo) Purpose: Va...

(GITHUB)

---

[uncategorized] ~298-~298: The official name of this software platform is spelled with a capital “H”.
Context: ...ription in database:** - Insert into github_subscriptions table - Include all m...

(GITHUB)

AGENTS.md

[style] ~326-~326: In American English, abbreviations like “etc.” require a period.
Context: ...ou need data prior (channelId, spaceId, etc): ```typescript bot.sendMessage(channe...

(ETC_PERIOD)

🪛 markdownlint-cli2 (0.18.1)

GITHUB_APP_IMPLEMENTATION_PLAN.md

221-221: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

🔇 Additional comments (18)

.env.sample (1)

1-31: ✓ Environment variables properly documented.

The additions of OAUTH_REDIRECT_URL and DRIZZLE_MIGRATIONS_PATH are well-commented and consistent with the configuration guidance in CONTRIBUTING.md. The optional nature is clear via empty defaults.

README.md (4)

74-74: Reference to CONTRIBUTING.md for detailed environment configuration is clear.

The README now properly separates user-facing setup from developer-facing configuration details.

---

123-130: GitHub App Setup section appropriately defers to CONTRIBUTING.md.

This high-level overview with reference to detailed instructions in CONTRIBUTING.md (lines 116–173) provides good separation of concerns.

---

132-174: Usage section is clear but verify event type completeness.

The subscription and query commands are well-documented. However, line 150 lists event types as pr, issues, commits, releases, ci, comments, reviews, branches, forks, stars, all. Confirm this matches the actual event filtering implementation in the codebase.

---

213-239: Future Enhancements section is well-organized.

Separating "Completed" and categorizing planned features (Subscription & UX, Event Organization, Commands & Queries, Automation) improves clarity for contributors and users.

CONTRIBUTING.md (3)

55-90: Environment variables documentation is comprehensive and well-formatted.

Tables clearly distinguish between required, GitHub App optional, and other optional variables. However, verify the PORT default on line 82. The .env.sample shows PORT=5123 but the table here shows 3000 as the default.

---

116-173: GitHub App Setup instructions are detailed and actionable.

Step-by-step guidance with repository permissions, OAuth settings, and environment variable configuration is thorough. Verify line 125 webhook URL format (/github-webhook) matches the actual route used in the application.

---

196-220: Development Workflow and Project Structure are clear.

Code quality commands and directory layout provide good context for contributors. Structure looks reasonable for the described bot architecture.

GITHUB_APP_IMPLEMENTATION_PLAN.md (3)

213-240: Subscription flow rewrite clarifies unified OAuth approach.

The new flow description (single OAuth flow with subscription created during callback) is clearer than before. However, verify that this implementation is complete: line 292 describes private repos without app installation returning an error page. Confirm this error handling is actually implemented in the OAuth callback handler.

---

317-327: Installation URL with smart targeting is well-documented but requires verification.

Line 320 suggests pre-selecting the target account using target_id=<owner.id> in the GitHub App installation URL. Verify this parameter is supported by the current GitHub App API and that the format matches actual GitHub endpoints.

---

509-535: Private repo OAuth support strategy is sound but references external service.

Lines 509-527 describe using GitHubOAuthService for private repo access via user tokens. Verify that this service exists and is properly integrated into command handlers as described in the "Changes Required" section (lines 528-533).

AGENTS.md (6)

1-14: Quick Start is concise and emphasizes stateless architecture.

The condensed intro is much more actionable than before. The CRITICAL note on line 13 about stateless architecture is appropriately positioned for developer awareness.

---

114-114: Verify bot.appAddress property usage in tip handler example.

Line 114 uses bot.appAddress to check if the bot received a tip. Confirm this is the correct property name for the bot's smart account address per the Towns Protocol bot SDK.

---

196-196: Verify getSmartAccountFromUserId is correctly exported.

Line 196 imports getSmartAccountFromUserId from "@towns-protocol/bot". Ensure this function exists, is exported with this exact name, and accepts the parameters shown in lines 198–201.

---

268-319: Web3 / Contract Interactions section provides good examples but requires verification.

The examples for reading contracts (lines 283–288), writing (lines 297–298), and execute() batch operations (lines 311–318) are well-structured. However, verify:

1. Line 281: The tuple (bot.viem, bot.appAddress, bot.botId) - are these the actual access points for Web3 interactions?
2. Line 296: The simpleAppAbi import path '@towns-protocol/bot/simpleAppAbi' - verify this export exists.
3. Line 301: The execute() import from 'viem/experimental/erc7821' - confirm this experimental API is stable enough to recommend.

---

323-350: External Interactions pattern is practical and clear.

The GitHub integration pattern (lines 335–347) demonstrates good practice for storing state outside the bot and using webhooks. The mention of patterns on line 349 is appropriately brief.

---

351-357: Critical Notes section provides essential reminders.

All five critical notes are important and well-prioritized. Verify line 357 aligns with actual gas payment requirements for on-chain operations (i.e., confirm funding bot.viem.account is correct vs other property names).

CLAUDE.md (1)

1-1: Reference to updated AGENTS.md is appropriate.

This file correctly points to the rewritten AGENTS.md with consolidated guidance.