docs(readme): markdown-only + mobile-safe listing (no raw HTML)#71
Conversation
Reddit's App Directory README renderer is markdown-only: it shows raw HTML (<div>, <img>, <strong>, <details>) as literal text, and the wide ASCII diagram + 5-column table forced horizontal overflow on mobile. Rewrite the README in pure markdown: - Banner: markdown image with an absolute raw-GitHub URL (responsive, renders on both GitHub and the listing) instead of an HTML <img> (which rendered as literal text on the listing). - Drop all raw HTML (centered <div>, <strong>, <br>). - Convert the vs-AutoMod comparison table to bullets (wide tables overflow on narrow mobile). - Move the architecture (ASCII diagram + by-construction guarantees) and the developer reference into docs/architecture.md + docs/for-developers.md, linked from the README. <details> folding isn't supported on the Reddit listing, so keeping the listing short + mod-facing means the depth lives in linked docs. The listing reflects this at the next publish (the README is a publish-time snapshot); GitHub renders it immediately. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
변경 사항 요약README와 신규 문서 파일을 통해 프로젝트 문서를 체계적으로 재구성했습니다. README를 마크다운 중심으로 단순화하고, 아키텍처 및 개발자 가이드 문서를 별도로 분리하여 각 대상층(사용자, 아키텍처 이해자, 개발자)의 요구사항을 명확히 분담합니다. 변경 사항문서 재구성 및 확장
관련 PR
예상 코드 검토 노력🎯 1 (Trivial) | ⏱️ ~5 분
🚥 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 refactors the project's documentation by extracting the detailed architecture and developer-focused sections from the main README.md into two new dedicated files: docs/architecture.md and docs/for-developers.md. The README.md has been updated to be more concise, providing high-level overviews and linking to the new documentation for deeper technical details. Review feedback suggests improving the navigability of these new documents by converting plain text file paths and section references into functional Markdown links.
| | LLM calls per rule | exactly **1**, at edit time | [`src/server/routes/compose.ts`](../src/server/routes/compose.ts) | | ||
| | 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) | README → _Fetch domains_ | |
There was a problem hiding this comment.
This reference to the README section is currently plain text. Converting it to a Markdown link improves the documentation's usability by allowing readers to navigate directly to the detailed explanation of fetch domains, especially since other entries in this table are already linked to their respective source files.
| | Reddit content sent to the LLM | **none** (only the mod's typed sentence) | README → _Fetch domains_ | | |
| | Reddit content sent to the LLM | **none** (only the mod's typed sentence) | [README → _Fetch domains_](../README.md#fetch-domains) | |
| | `docs/devvit-setup-guide.md` | how to take this repo to a published Devvit app (wizard → upload → settings → playtest → publish) | | ||
| | `docs/architecture.md` | build-time-AI / runtime-determinism design + the by-construction guarantees | |
There was a problem hiding this comment.
These documentation paths are currently plain text. Since these files reside in the same directory, converting them to relative Markdown links would improve navigability within the documentation, maintaining consistency with how for-developers.md is linked from the architecture document.
| | `docs/devvit-setup-guide.md` | how to take this repo to a published Devvit app (wizard → upload → settings → playtest → publish) | | |
| | `docs/architecture.md` | build-time-AI / runtime-determinism design + the by-construction guarantees | | |
| | [docs/devvit-setup-guide.md](./devvit-setup-guide.md) | how to take this repo to a published Devvit app (wizard → upload → settings → playtest → publish) | | |
| | [docs/architecture.md](./architecture.md) | build-time-AI / runtime-determinism design + the by-construction guarantees | |
![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 `@docs/architecture.md`:
- Around line 6-23: The fenced code block in docs/architecture.md (the
multi-line ASCII diagram wrapped by triple backticks) is missing a language tag
causing markdownlint MD040; update that specific fenced block (the diagram
starting "Moderator types a rule" and ending with "rate-limit breaker (5 min)")
to include a language specifier like "text" (e.g., change ``` to ```text) so the
linter recognizes it as a non-code/text block.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 403d2a6f-23df-4e00-b0a4-35516a98eed3
📒 Files selected for processing (3)
README.mddocs/architecture.mddocs/for-developers.md
| ``` | ||
| 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) ──► fact bag from the item + author + sub 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) | ||
| ``` |
There was a problem hiding this comment.
펜스 코드블록에 언어 지정이 빠져 markdownlint(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)
@@
Scheduler: audit retention (daily) · dry-run replay · shadow-promote check (15 min) · rate-limit breaker (5 min)
-```
+```🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 6-6: 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 `@docs/architecture.md` around lines 6 - 23, The fenced code block in
docs/architecture.md (the multi-line ASCII diagram wrapped by triple backticks)
is missing a language tag causing markdownlint MD040; update that specific
fenced block (the diagram starting "Moderator types a rule" and ending with
"rate-limit breaker (5 min)") to include a language specifier like "text" (e.g.,
change ``` to ```text) so the linter recognizes it as a non-code/text block.
1 participant
The App Directory listing renders the repo README, and Reddit's renderer is markdown-only — it printed our raw HTML (
<div>,<img>,<strong>,<details>) as literal text, showed no banner, and the wide ASCII diagram + 5-col table caused horizontal overflow on mobile.Rewrite the README in pure markdown:
raw.githubusercontent.comURL (responsive; renders on GitHub and the listing). The current banner is the original-robot art (no Snoo), so it's safe on the reviewed listing.<div align>,<strong>,<br>).docs/architecture.md+docs/for-developers.md, linked from the README —<details>folding isn't supported on the listing, so the listing stays short + mod-facing and the depth lives in linked docs.The listing picks this up at the next
devvit publish(README is a publish-time snapshot); GitHub renders it immediately. No content lost — reorganized + de-HTML'd.🤖 Generated with Claude Code
Summary by CodeRabbit
📋 릴리스 노트