docs(readme): restructure as a moderator-facing app listing#67
Conversation
The App Directory listing renders the repo README verbatim (confirmed
against Bot Bouncer, Comment Mop, Remove Macro, Admin Tattler -- each
shows its README as the listing). Those apps keep their README
user-facing; ours read like a dev/judge doc, which is what moderators
saw on the install page.
Restructure so the listing reads like a product page:
- Lead mod-facing: what it does (plain) -> how to use -> settings -> why
a new rule can't hurt your sub -> how it compares to AutoMod.
- Fold the dev/architecture depth into <details> ("How it works",
"For developers") -- collapsed for moderators, expandable for judges.
- Keep Fetch domains + Permissions visible (review-required + reassuring).
Re-publishing refreshes the listing to this version.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
개요README를 재구조화하여 프로젝트의 핵심 메시지와 아키텍처를 명확히 했으며, 개발자 가이드와 Changelog를 갱신했습니다. 함수형 변경 없음, 문서 콘텐츠만 정렬 및 갱신. 변경사항README 재구조화
예상 코드 리뷰 노력🎯 2 (Simple) | ⏱️ ~12 minutes 토끼의 시
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
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. Comment |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request significantly restructures and rewrites the README.md to improve clarity and accessibility for moderators. Key changes include the addition of simplified usage guides, safety guarantees, and a comparison table with AutoModerator, while technical architecture and developer details have been moved into collapsible sections. Feedback suggests refining the architecture diagram to accurately reflect the data flow between the 'fact bag' and the evaluator, and adding internal markdown links for better navigation.
| ▼ | ||
| Deterministic evaluator (pure TS, 0 network, 0 LLM) | ||
| │ builds a "fact bag" from the post/comment + account + subreddit-scoped Redis state | ||
| Deterministic evaluator (pure TS, 0 network, 0 LLM) ──► builds a "fact bag" from the item + author + state |
There was a problem hiding this comment.
The architecture diagram implies that the "Deterministic evaluator" builds the "fact bag". However, based on the code structure (e.g., src/server/evaluator.ts and the existence of src/server/fact-bag.ts), the fact bag is an input to the evaluator. Reversing the arrow or clarifying the flow would improve technical accuracy for judges and developers.
| Deterministic evaluator (pure TS, 0 network, 0 LLM) ──► builds a "fact bag" from the item + author + state | |
| Build "fact bag" (item + author + state) ──► Deterministic evaluator (pure TS, 0 LLM) |
| | New-rule blast radius for first 24h | **0 live actions** (shadow default on) | `shadow: true` in [`rule-schema.ts`](./src/shared/rule-schema.ts) | | ||
| | Live action reversibility | **100% for 30 days** (per-action undo) | [`src/server/executor.ts`](./src/server/executor.ts) | | ||
| | Reddit content sent to the LLM | **none** (only the mod's typed sentence) | *Fetch domains*, below | | ||
| | Reddit content sent to the LLM | **none** (only the mod's typed sentence) | _Fetch domains_, above | |
There was a problem hiding this comment.
The reference to the "Fetch domains" section is currently plain text. For better navigation, especially in a long README, this should be a markdown link to the corresponding section header.
| | Reddit content sent to the LLM | **none** (only the mod's typed sentence) | _Fetch domains_, above | | |
| | Reddit content sent to the LLM | **none** (only the mod's typed sentence) | [Fetch domains](#fetch-domains), above | |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@README.md`:
- Around line 100-117: The fenced ASCII diagram block in README.md is missing a
language identifier and triggers MD040; update the code fence that wraps the
diagram (the triple-backtick block containing the moderator/OpenAI/Redis flow)
to include a language tag such as text (i.e., change ``` to ```text) so the
linter recognizes it as a text code block and the MD040 warning is resolved.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
| ``` | ||
| Moderator types a rule | ||
| │ (only the moderator's sentence is sent — never Reddit content) | ||
| ▼ | ||
| OpenAI gpt-5.4-mini ──► JSON ──► Zod strict parse + action whitelist ──► rules:draft (Redis) | ||
| (build-time only, (reject if invalid) | ||
| reasoning_effort: none) | ||
| (build-time only) (reject if invalid) | ||
| │ dry-run preview / activate | ||
| ▼ | ||
| rules:active (Redis) | ||
| │ | ||
| Reddit triggers (onPostSubmit / onCommentSubmit / onPostReport / onCommentReport / onPostFlairUpdate) | ||
| ▼ | ||
| Deterministic evaluator (pure TS, 0 network, 0 LLM) | ||
| │ builds a "fact bag" from the post/comment + account + subreddit-scoped Redis state | ||
| Deterministic evaluator (pure TS, 0 network, 0 LLM) ──► builds a "fact bag" from the item + author + state | ||
| ▼ | ||
| Action executor ──► shadow? log only : live? act + write rollback token (30-day TTL) + audit entry | ||
| Action executor ──► shadow? log only : live? act + write 30-day undo token + audit entry | ||
| ▲ | ||
| Scheduler: audit retention (daily) · dry-run replay (one-shot) · shadow-promote check (15 min) · rate-limit breaker (5 min) | ||
| Scheduler: audit retention (daily) · dry-run replay · shadow-promote check (15 min) · rate-limit breaker (5 min) | ||
| ``` |
There was a problem hiding this comment.
코드 펜스에 언어 식별자를 지정해 주세요.
현재 ASCII 다이어그램 fenced block에 언어가 없어 MD040 경고가 발생합니다. text를 지정하면 린트 경고를 제거할 수 있습니다.
수정 예시
-```
+```text
Moderator types a rule
│ (only the moderator's sentence is sent — never Reddit content)
▼
OpenAI gpt-5.4-mini ──► JSON ──► Zod strict parse + action whitelist ──► rules:draft (Redis)
(build-time only) (reject if invalid)
│ dry-run preview / activate
▼
rules:active (Redis)
│
Reddit triggers (onPostSubmit / onCommentSubmit / onPostReport / onCommentReport / onPostFlairUpdate)
▼
Deterministic evaluator (pure TS, 0 network, 0 LLM) ──► builds a "fact bag" from the item + author + state
▼
Action executor ──► shadow? log only : live? act + write 30-day undo token + audit entry
▲
Scheduler: audit retention (daily) · dry-run replay · shadow-promote check (15 min) · rate-limit breaker (5 min)</details>
<!-- suggestion_start -->
<details>
<summary>📝 Committable suggestion</summary>
> ‼️ **IMPORTANT**
> Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
```suggestion
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 100-100: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@README.md` around lines 100 - 117, The fenced ASCII diagram block in
README.md is missing a language identifier and triggers MD040; update the code
fence that wraps the diagram (the triple-backtick block containing the
moderator/OpenAI/Redis flow) to include a language tag such as text (i.e.,
change ``` to ```text) so the linter recognizes it as a text code block and the
MD040 warning is resolved.
1 participant
Why
The App Directory listing renders the repo README verbatim — confirmed by inspecting other published apps (Bot Bouncer, Comment Mop, Remove Macro, Admin Tattler all show their README as the listing). Those apps keep their README user-facing; ours read like a dev/judge doc, so moderators on the install page saw architecture diagrams, npm commands, and
src/...paths.What
Restructure so the listing reads like a product page, with the technical depth folded for judges:
Always visible (moderator-facing): what it does (plain) → how to use → settings → "why a new rule can't hurt your community" → how it compares to AutoMod → fetch domains → permissions.
Folded into
<details>(expand on GitHub): "🔧 How it works (architecture)" (ASCII diagram, by-construction guarantees table) and "💻 For developers" (npm commands, file layout, CI).<details>collapses on GitHub for judges; on the Reddit listing the moderator-facing top is what leads. Re-publishing refreshes the listing to this version. No content was lost — just reordered and folded.🤖 Generated with Claude Code
Summary by CodeRabbit
릴리스 노트