docs: add repository guidelines and documentation - #31
Merged
kumawatkaran523 merged 8 commits intoAug 12, 2026
Conversation
WalkthroughUpdated repository documentation for maintainers, contributors, project practices, testing, checklist status, branding, and ignored build artifacts. No exported or public entities changed. ChangesRepository Documentation
Estimated code review effort: 1 (Trivial) | ~2 minutes Suggested labels: Poem
🚥 Pre-merge checks | ✅ 4✅ Passed checks (4 passed)
✨ 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 |
github-actions
Bot
added
documentation
Contributor
Atharva0506
marked this pull request as ready for review
August 10, 2026 15:03
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 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 `@MAINTAINERS.md`:
- Around line 15-21: Confirm the current maintainer and mentor assignments, then
reconcile the maintainer and mentor sections in README.md and MAINTAINERS.md so
both documents contain the same authoritative roster, including the correct
roles for Bruno, Atharva, Karn, and Aditya.
- Around line 1-3: Align MAINTAINERS.md with its stated scope by either adding
an Ideators section containing the required columns and roster entries alongside
the existing Maintainers and Mentors sections, or removing the title,
introduction, and links that promise Ideator coverage; ensure the final document
does not claim to list Ideators without providing that roster.
🪄 Autofix
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: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: a369efc9-0baf-4456-9b0f-93a3dfc5ff08
📒 Files selected for processing (1)
MAINTAINERS.md
Atharva0506
changed the title
- Add brand/ kit (logos, generated favicons, color palette) with Brand.md - Fill in BestPracticesChecklist.md with objectively verifiable current state - Add AGENTS.md - Fix CONTRIBUTING.md template TODO placeholders and link the #thrubox Discord channel - Add README test instructions; fix stale Maintainers list to point at MAINTAINERS.md
github-actions
Bot
added
configuration
There was a problem hiding this comment.
Actionable comments posted: 6
🤖 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 `@AGENTS.md`:
- Around line 18-24: Reorder the verification commands in AGENTS.md so go vet
./... and go test ./... run before the blocking ./relay-server command, or
explicitly instruct users to start the server in a separate terminal.
- Around line 26-27: Fix the reported MD031 violations by adding a blank line
after “Docker:” in AGENTS.md (lines 26-27) and blank lines after each of the
three numbered setup headings in CONTRIBUTING.md (lines 88-99), before their
fenced code blocks.
- Line 35: The dependency policy is inconsistent with the direct runtime
dependencies declared in go.mod. In AGENTS.md at lines 35-35, replace the
“standard library plus mattn/go-sqlite3 only” constraint with the supported
policy that includes all approved direct runtime dependencies; in
CONTRIBUTING.md at lines 227-227, remove the “zero external runtime dependencies
beyond SQLite” claim or update it to list the same supported dependencies.
Ensure both documents use consistent policy wording.
In `@BestPracticesChecklist.md`:
- Line 34: Update BestPracticesChecklist.md by adding blank lines before and
after the score table containing the Total row, and add a blank line between the
“### Backend / API Notes” heading and its following list to satisfy Markdown
formatting rules.
- Around line 233-234: Update the dynamic_analysis_unsafe checklist entry to
mark it unmet rather than N/A, reflecting that the CGo-based
github.com/mattn/go-sqlite3 path is outside Go’s memory-safety guarantees.
Document Valgrind or AddressSanitizer usage for SQLite-enabled builds and tests
if available; otherwise retain an explicit justification that no such analysis
is documented.
In `@brand/Brand.md`:
- Around line 1-3: Update Brand.md and the related README asset references to
document that brand/ is the canonical source synchronized into public/ for
bundled application consumers, or change README links to use the canonical
brand/ files. Clarify that the bundled application lacks a web UI rather than
implying the repository has no HTML consumers, and preserve the existing asset
names and usage context.
🪄 Autofix
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: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: cac836fd-cb47-413e-a297-a06284691c31
⛔ Files ignored due to path filters (8)
brand/aossie-logo.svgis excluded by!**/*.svgbrand/apple-touch-icon.pngis excluded by!**/*.pngbrand/favicon-16x16.pngis excluded by!**/*.pngbrand/favicon-32x32.pngis excluded by!**/*.pngbrand/favicon-48x48.pngis excluded by!**/*.pngbrand/favicon.icois excluded by!**/*.icobrand/icon-512.pngis excluded by!**/*.pngbrand/thrubox-logo.svgis excluded by!**/*.svg
📒 Files selected for processing (6)
AGENTS.mdBestPracticesChecklist.mdCONTRIBUTING.mdREADME.mdbrand/Brand.mdchecklist-status.json
- MAINTAINERS.md: note no Ideators assigned instead of silently omitting the section - AGENTS.md: run go vet/go test before the blocking server start; fix dependency list - CONTRIBUTING.md: fix dependency policy claim (go.mod has uuid/yaml.v3 too), markdown formatting - BestPracticesChecklist.md: markdown formatting; mark dynamic_analysis_unsafe unmet (CGo/SQLite path) - brand/Brand.md: clarify public/ vs brand/ asset relationship
adityabhattad2021
approved these changes
Aug 11, 2026
There was a problem hiding this comment.
Actionable comments posted: 2
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (2)
CONTRIBUTING.md (1)
12-12: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick winReconcile the Discord-only policy with the GitHub issue workflow.
Lines 9-14 require Discord for all communication and state that GitHub is for code only. Lines 31-54 still require contributors to report bugs and create an issue first. Define one authoritative workflow. If GitHub issues remain required, state that issues are the tracking record and Discord is for discussion and updates.
🤖 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 `@CONTRIBUTING.md` at line 12, Reconcile the contribution communication guidance by updating the Discord-only policy near the removed mandatory `#thrubox` instruction and the bug-report workflow section. Define GitHub issues as the authoritative tracking record if issue creation remains required, while reserving Discord for discussion and updates; remove any contradictory requirement that all communication occur exclusively in Discord.BestPracticesChecklist.md (1)
25-35: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick winAdd blank lines around the score table.
markdownlint-cli2reports MD058 at Line 34. Add one blank line before the table and one blank line after the table, before the horizontal rule.Proposed fix
<!-- Auto-updated by checklist-score.yml workflow — do not edit manually --> + | Category | Met | Total | Status | |--------------------|-----|-------|--------| | Basics | 8 | 8 | ✅ | | Change Control | 5 | 6 | 🟡 | | Reporting | 3 | 8 | 🔴 | | Quality | 4 | 11 | 🔴 | | Security | 4 | 9 | 🔴 | | Analysis | 2 | 7 | 🔴 | | **Total** | **26** | **49** | **53%** | + ---🤖 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 `@BestPracticesChecklist.md` around lines 25 - 35, Add a blank line immediately before the score table and another immediately after the table, before the horizontal rule, while preserving the auto-generated marker and table content.Source: Linters/SAST tools
🤖 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 @.gitignore:
- Line 34: Update the relay entry in .gitignore from an unanchored pattern to
/relay so only the repository-root build artifact is ignored, while preserving
nested cmd/relay files.
In `@brand/Brand.md`:
- Line 27: Update the README consumer statement in Brand.md to distinguish the
synchronized logo copies under public/—consumed by README.md—from the favicon
and icon files, which are consumed only by external dashboards, status pages, or
documentation sites. Do not state that README.md consumes the favicon or icon
files.
---
Outside diff comments:
In `@BestPracticesChecklist.md`:
- Around line 25-35: Add a blank line immediately before the score table and
another immediately after the table, before the horizontal rule, while
preserving the auto-generated marker and table content.
In `@CONTRIBUTING.md`:
- Line 12: Reconcile the contribution communication guidance by updating the
Discord-only policy near the removed mandatory `#thrubox` instruction and the
bug-report workflow section. Define GitHub issues as the authoritative tracking
record if issue creation remains required, while reserving Discord for
discussion and updates; remove any contradictory requirement that all
communication occur exclusively in Discord.
🪄 Autofix
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: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: de55c8e4-68f7-466f-b49f-e169c57828dc
📒 Files selected for processing (7)
.gitignoreAGENTS.mdBestPracticesChecklist.mdCONTRIBUTING.mdMAINTAINERS.mdbrand/Brand.mdchecklist-status.json
|
|
||
| # Build / Release | ||
| dist/ | ||
| relay |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
git check-ignore -v --no-index cmd/relayRepository: AOSSIE-Org/ThruBox-Server
Length of output: 193
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf '%s\n' '--- .gitignore ---'
cat -n .gitignore
printf '%s\n' '--- AGENTS.md references ---'
rg -n -C 3 'cmd/relay|(^|[^[:alnum:]_])relay([^[:alnum:]_]|$)' AGENTS.md . 2>/dev/null | head -200
printf '%s\n' '--- tracked relay paths ---'
git ls-files | rg '(^|/)relay($|/)' || true
printf '%s\n' '--- ignore checks ---'
for path in relay cmd/relay cmd/relay/main.go; do
printf '%s: ' "$path"
git check-ignore -v --no-index "$path" || true
done
printf '%s\n' '--- repository status ---'
git status --short --untracked-files=allRepository: AOSSIE-Org/ThruBox-Server
Length of output: 11804
Anchor the relay ignore rule to the repository root.
The current rule ignores cmd/relay and its files. Change it to /relay if it targets a root-level build artifact.
Proposed fix
-relay
+/relay📝 Committable suggestion
‼️ 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.
Suggested change
| relay | |
| /relay |
🤖 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 @.gitignore at line 34, Update the relay entry in .gitignore from an
unanchored pattern to /relay so only the repository-root build artifact is
ignored, while preserving nested cmd/relay files.
| | [`apple-touch-icon.png`](./apple-touch-icon.png) | 180×180 | iOS home screen | | ||
| | [`icon-512.png`](./icon-512.png) | 512×512 | PWA manifest / app icon | | ||
|
|
||
| This server itself has no bundled web UI (it's a headless REST API) — the favicons/icons here aren't consumed by any application HTML, only by the repo's own README and any external dashboards, status pages, or documentation sites built around this server. |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Correct the README consumer statement.
README.md, Lines 4-8 use the synchronized logo copies under public/. They do not consume the favicon or icon files listed in this section. State the logo consumer and the favicon/icon consumers separately.
Proposed wording
-This server itself has no bundled web UI (it's a headless REST API) — the favicons/icons here aren't consumed by any application HTML, only by the repo's own README and any external dashboards, status pages, or documentation sites built around this server.
+This server itself has no bundled web UI (it's a headless REST API). The synchronized logo copies under `public/` are consumed by the repository README. The favicon and icon assets in this folder are available for external dashboards, status pages, or documentation sites built around this server.🤖 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 `@brand/Brand.md` at line 27, Update the README consumer statement in Brand.md
to distinguish the synchronized logo copies under public/—consumed by
README.md—from the favicon and icon files, which are consumed only by external
dashboards, status pages, or documentation sites. Do not state that README.md
consumes the favicon or icon files.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Addressed Issues:
N/A
Screenshots/Recordings:
N/A (documentation-only change)
Additional Notes:
Adds repository guidelines and documentation per AOSSIE's midterm repo-quality checklist:
MAINTAINERS.md— Mentors and Maintainers per AOSSIE's role definitionsbrand/kit — logo, generated favicons/icons,Brand.mddocumenting the color palette (sourced from the existing logo)BestPracticesChecklist.md— filled in with objectively verifiable current state (self-certification items and a couple of genuine gaps — e.g. no test files or linter wired into CI yet — left open for a maintainer)AGENTS.md— build/test/contribution instructions for AI coding agentsTODO/YOUR_USERNAME/TODO.gitplaceholders inCONTRIBUTING.md#thruboxDiscord channel inCONTRIBUTING.md(previously only the general server invite)MAINTAINERS.mdUsed Claude Code with model Claude Sonnet 5 to draft this documentation and generate the favicon assets.
Checklist
Summary by CodeRabbit