docs: comprehensive documentation overhaul for AI agents and developers#86
Merged
fredcamaral merged 5 commits intodevelopfrom Apr 1, 2026
Merged
docs: comprehensive documentation overhaul for AI agents and developers#86fredcamaral merged 5 commits intodevelopfrom
fredcamaral merged 5 commits intodevelopfrom
Conversation
- CLAUDE.md (593 lines): rewritten with verified file paths, accurate Makefile targets, Quick Start section, updated code patterns from develop branch - AGENTS.md (175 lines): standalone universal AI agent entry point (replaced symlink), covers architecture, commands, conventions, security patterns, and forbidden practices - llms.txt (62 lines): new file following llmstxt.org spec, structured index of all documentation and codebase resources - README.md (237 lines): improved for open-source developers, added prerequisites, contributing guide, fixed infrastructure ports, updated migration count - PROJECT_RULES.md (411 lines): added missing patterns (syncer, cross-adapters, object storage, systemplane), fixed stale references, added missing libraries and Make targets
- Fix AuditRepository → AuditLogRepository - Fix M2M → M2MProvider - Fix IdempotencyService → IdempotencyRepository - Condense PDF library migration notes (CodeRabbit feedback)
WalkthroughAdded and reorganized project documentation: new AGENTS.md and llms.txt; major rewrites to CLAUDE.md and README.md; updates to docs/PROJECT_RULES.md. Changes expand quick-starts, architecture/bounded-context guidance, coding/testing conventions, multi-tenancy rules, infra/migrations, and CI/tooling. No code or exported APIs changed. Changes
(Note: cohorts group related documentation edits; many README/CLAUDE references point to other repo files—validate those targets.) 🚥 Pre-merge checks | ✅ 2✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. Comment |
Contributor
|
Consider updating CHANGELOG.md to document this change. If this change doesn't need a changelog entry, add the |
Contributor
|
This PR is very large (5 files, 1583 lines changed). Consider breaking it into smaller PRs for easier review. |
![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 the current code and only fix it if needed.
Inline comments:
In `@CLAUDE.md`:
- Line 591: Update the stale metadata string "Last Updated: March 2026" to
reflect the PR date by replacing it with the current date (e.g., "Last Updated:
April 1, 2026" or "Last Updated: April 2026") so the document header is
accurate; locate the exact text "Last Updated: March 2026" in CLAUDE.md and edit
that line accordingly.
In `@README.md`:
- Line 175: Change the phrase "Full stack journey tests" to use a hyphenated
compound adjective: replace "Full stack journey tests against running services"
with "Full-stack journey tests against running services" so the README uses
correct compound-modifier punctuation for the phrase found as "Full stack
journey tests" in the README content.
🪄 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: ASSERTIVE
Plan: Pro
Run ID: af3ff91e-014a-4d56-8f10-5d45cc39c9f1
📒 Files selected for processing (6)
AGENTS.mdAGENTS.mdCLAUDE.mdREADME.mddocs/PROJECT_RULES.mdllms.txt
- CLAUDE.md: update Last Updated from March 2026 to April 2026 - README.md: hyphenate 'Full-stack' compound adjective
Contributor
|
Consider updating CHANGELOG.md to document this change. If this change doesn't need a changelog entry, add the |
Contributor
|
This PR is very large (5 files, 1583 lines changed). Consider breaking it into smaller PRs for easier review. |
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@CLAUDE.md`:
- Line 22: The CLAUDE.md toolchain claim is out of sync with go.mod; either
remove the "toolchain: 1.26.1" reference from CLAUDE.md or add a matching
toolchain directive to go.mod. To fix, open CLAUDE.md and delete or update the
"toolchain: 1.26.1" text, or open go.mod and add a toolchain directive matching
the doc (e.g., a "toolchain" line for 1.26.1) so the documented toolchain and
the go directive ("go 1.26.0") are consistent.
In `@README.md`:
- Line 99: Replace the vague sentence "Swagger UI is accessible in development
mode" with a precise URL path by stating the exact endpoint where Swagger is
served (for example: "Swagger UI is available at http://localhost:4018/swagger"
or whichever route your app exposes), and if applicable add a short note about
env-specific availability (e.g., "accessible at /swagger only when
NODE_ENV=development"); update the README line that currently reads "The API is
available at `http://localhost:4018`. Swagger UI is accessible in development
mode." to include the exact path.
- Line 105: The README references a non-existent file
config/.config-map.example; either correct the path or point to the actual
config example file. Open README.md, find the sentence containing
`config/.config-map.example` and replace it with the correct file location or
remove the reference and link to the existing config example (or add the missing
file under config/ with the expected name). Ensure the updated reference matches
the repository's actual filename and format so the README points to a valid
resource.
🪄 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: ASSERTIVE
Plan: Pro
Run ID: bb119f73-d39a-489a-a746-7a26f89cea7d
📒 Files selected for processing (2)
CLAUDE.mdREADME.md
Contributor
|
Consider updating CHANGELOG.md to document this change. If this change doesn't need a changelog entry, add the |
Contributor
|
This PR is very large (5 files, 1583 lines changed). Consider breaking it into smaller PRs for easier review. |
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@CLAUDE.md`:
- Line 265: The docs incorrectly call protected(resource, actions...) a
"higher-order function"; update the wording to say it's a closure field on the
Routes struct (Routes.Protected) rather than a standalone function and note that
it is initialized at runtime by RegisterRoutes in internal/bootstrap/routes.go
(see the Protected func field declaration and its initialization in
RegisterRoutes). Adjust the sentence in CLAUDE.md to explicitly reference the
closure field name ("Protected" on Routes) and that contributors should look in
internal/bootstrap/routes.go for its initialization.
- Around line 439-441: Update the wording around the package references to avoid
confusion: clarify that "commons/assert" and "commons/runtime" are provided by
the external lib-commons library and that `pkg/assert` and `pkg/runtime` are
shorthand references used in the docs (not local pkg/ imports); likewise clarify
`commons/systemplane` origin. Edit the lines mentioning "referred to as
`pkg/assert`" and "`pkg/runtime`" so they explicitly state they are
documentation shorthand mapping to the lib-commons import paths (e.g.,
lib-commons/commons/assert, lib-commons/commons/runtime) rather than implying
files under a local pkg/ directory.
In `@README.md`:
- Line 184: The README contains conflicting statements about Swagger UI
location: replace or reconcile the sentence "Swagger UI is accessible at the
service root" with a clear statement that Swagger UI is served at
/swagger/index.html (e.g., "When running in development mode, Swagger UI is
accessible at http://localhost:4018/swagger/index.html") and, if desired, add a
short note about the root path behavior (e.g., whether the root redirects to
/swagger/index.html or not) so both the explicit URL and the root behavior are
unambiguous.
- Line 72: The README currently says "Go 1.26+" while CLAUDE.md's go.mod uses
"go 1.26.0" and the Docker table uses "golang:1.26.1-alpine", causing
inconsistent precision; pick a single canonical Go version (recommend 1.26.1 to
match Docker) and update all references so they match exactly: change the README
entry "Go 1.26+" to "Go 1.26.1", update CLAUDE.md's go.mod `go 1.26.0` to `go
1.26.1` (or vice-choose the agreed patch level), and ensure the Docker table
string `golang:1.26.1-alpine` remains consistent with the chosen version.
🪄 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: ASSERTIVE
Plan: Pro
Run ID: 0182fe33-ed2b-47d4-823e-8bac6b25a7aa
📒 Files selected for processing (2)
CLAUDE.mdREADME.md
…ersion, fix Swagger path
Contributor
Author
|
@coderabbitai resolve |
There was a problem hiding this comment.
♻️ Duplicate comments (2)
CLAUDE.md (1)
265-265:⚠️ Potential issue | 🟡 MinorClarify
protected(...)usage on Line 265: it is aRoutes.Protectedclosure field, not a standalone function.Current wording can send readers to the wrong place during implementation/debugging.
Suggested wording
-- Route registration uses `protected(resource, actions...)` higher-order function +- Route registration uses `routes.Protected(resource, actions...)` (closure field on `Routes`, initialized by `RegisterRoutes` in `internal/bootstrap/routes.go`)🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@CLAUDE.md` at line 265, The sentence "Route registration uses `protected(resource, actions...)` higher-order function" is misleading; update it to state that `protected` is the `Routes.Protected` closure field on the `Routes` type rather than a standalone higher-order function, so readers look up `Routes.Protected` (the closure field) when implementing or debugging route registration.README.md (1)
105-105:⚠️ Potential issue | 🟡 MinorPossible broken config example reference on Line 105.
config/.config-map.examplewas previously flagged as missing; if it still doesn’t exist, onboarding instructions are broken. Please verify and either update the path or point to the existing config example file.#!/bin/bash # Verify whether the referenced config example file exists (current branch). fd -t f --hidden --strip-cwd-prefix 'config-map.example' fd -t f --hidden --strip-cwd-prefix '\.config-map\.example'Expected: one of these commands should return the file referenced in docs; otherwise docs should be corrected.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@README.md` at line 105, The README references config/.config-map.example which may not exist; verify its presence in the repo (e.g., using the provided fd commands) and either update the README line "config/.config-map.example" to the correct existing path (for example config/config-map.example or .config-map.example) or add/restore the missing example file under config with the expected name; ensure the README text ("For production, override via environment variables... See [`config/.config-map.example`]") matches the actual file name you confirm.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Duplicate comments:
In `@CLAUDE.md`:
- Line 265: The sentence "Route registration uses `protected(resource,
actions...)` higher-order function" is misleading; update it to state that
`protected` is the `Routes.Protected` closure field on the `Routes` type rather
than a standalone higher-order function, so readers look up `Routes.Protected`
(the closure field) when implementing or debugging route registration.
In `@README.md`:
- Line 105: The README references config/.config-map.example which may not
exist; verify its presence in the repo (e.g., using the provided fd commands)
and either update the README line "config/.config-map.example" to the correct
existing path (for example config/config-map.example or .config-map.example) or
add/restore the missing example file under config with the expected name; ensure
the README text ("For production, override via environment variables... See
[`config/.config-map.example`]") matches the actual file name you confirm.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: 8ca5575d-5bf4-4089-9fbd-30bc0bb2bbbf
📒 Files selected for processing (2)
CLAUDE.mdREADME.md
Contributor
Author
|
@coderabbitai review |
✅ Actions performedReview triggered.
|
✅ Actions performedComments resolved and changes approved. |
Contributor
|
🎉 This PR is included in version 1.3.0-beta.7 🎉 The release is available on GitHub release Your semantic-release bot 📦🚀 |
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.
Summary
Comprehensive documentation overhaul covering all five key documentation files, bringing them to state-of-the-art quality for both AI coding agents and human developers.
Changes
CLAUDE.md (593 lines — rewritten)
1.26.0, CI pins1.26.1)AGENTS.md (175 lines — new file, replaced symlink)
llms.txt (62 lines — new file)
README.md (237 lines — improved)
docs/PROJECT_RULES.md (411 lines — improved)
Stats