docs: normalize README structure and add RELEASES.md

[nanotaboada]

Closes #448

Summary

• Removed: Table of Contents, Project Structure section, Testing section, Releases section
• Features capped at 6 bullets
• Architecture: replaced ~300-word prose subsections with a 2-line callout; added ADR one-liner
• API Reference: added HTTP response codes table
• Containers: absorbed Docker pull block from the removed Releases section
• Contributing: absorbed testing instructions (xUnit run + coverage commands)
• Command Summary: added AI Commands subsection (/pre-commit, /pre-release)
• New file: RELEASES.md with naming convention, full release workflow, and Docker pull examples

Test plan

• Verify Mermaid diagram renders correctly on GitHub
• Verify all internal links resolve (Swagger UI, adr/, CHANGELOG.md, CONTRIBUTING.md, copilot-instructions.md)
• Verify RELEASES.md is accessible from the repo root

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Reorganized README with expanded API reference including new Response Codes table for HTTP status codes (200, 201, 204, 400, 404, 409)
  • Added comprehensive release process documentation detailing automated deployment workflow and Docker image distribution
  • Updated command reference with new AI-assisted commands

[coderabbitai]

Warning

Rate limit exceeded

@nanotaboada has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 14 minutes and 37 seconds before requesting another review.

Your organization is not enrolled in usage-based pricing. Contact your admin to enable usage-based pricing to continue reviews beyond the rate limit, or try again in 14 minutes and 37 seconds.

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

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: e1058326-4fc7-45e5-ada9-8297d140302e

📥 Commits

Reviewing files that changed from the base of the PR and between 12a1782 and 50b31b4.

📒 Files selected for processing (3)

• .markdownlint.json
• README.md
• RELEASES.md

Walkthrough

This PR restructures the README to follow a standardized 13-section format per specification #448, removing verbose sections (Table of Contents, Project Structure, detailed Architecture, standalone Releases), consolidating others (Architecture into a brief callout), moving content (Testing and Releases to appropriate sections and a new file), and adding API response codes and AI command references. A new RELEASES.md file documents the release workflow and Docker image naming conventions.

Changes

Cohort / File(s)	Summary
README Restructuring README.md	Removed Table of Contents, Project Structure, and expanded Architecture subsections (~300 words). Consolidated Architecture into a 2–3 line blockquote. Added HTTP response codes table (200/201/204/400/404/409) to API Reference. Integrated "Pull Docker images" block into Containers section. Reintroduced Contributing section with Testing subsection containing test and coverage commands. Added AI Commands subsection to Command Summary with /pre-commit and /pre-release entries.
Release Documentation RELEASES.md	New file documenting release process with stadium-themed naming convention (v{SEMVER}-{STADIUM}), release workflow steps (branch → CHANGELOG update → PR → tag → CD), Docker pull examples for semantic version/stadium/latest tags, and automated CD workflow description.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~15 minutes

Assessment against linked issues

Objective	Addressed	Explanation
Remove Table of Contents, Project Structure, Testing, and Releases sections from README [#448]	✅
Normalize Architecture section to 2–3 line callout with arrow semantics [#448]	✅
Add HTTP response codes table to API Reference [#448]	✅
Add Docker pull examples for three tag formats to Containers section [#448]	✅
Add AI Commands subsection with /pre-commit and /pre-release to Command Summary [#448]	✅
Create RELEASES.md with naming convention, workflow, and Docker examples [#448]	✅
Absorb Testing section content into Contributing with test/coverage commands [#448]	✅
Cap Features at 6 bullets; confirm Swagger link; add .rest file mention; keep Environment Variables brief [#448]	❓	Summary does not detail changes to Features section bullet count, Swagger link presence, .rest file references, or Environment Variables section brevity—unable to confirm all requirements from provided summary.

Possibly related issues

• docs: normalize README structure python-samples-fastapi-restful#556: Implements the same README normalization (removing sections, adding response codes and AI commands) and new RELEASES.md with Docker tag examples and release workflow.
• docs: normalize README structure rust-samples-rocket-restful#61: Applies identical README restructuring (Architecture/Testing/Releases consolidation) and adds matching RELEASES.md with release process and Docker pull examples.
• docs: normalize README structure go-samples-gin-restful#242: Executes same README normalization pattern (removing verbose sections, adding response codes/AI commands) and introduces RELEASES.md with equivalent release documentation.
• docs: normalize README structure java.samples.spring.boot#296: Targets identical README restructuring (removing Table of Contents/Project Structure/Testing/Releases, consolidating Architecture, adding Response Codes/AI Commands) and RELEASES.md addition.
• docs: normalize README structure ts-node-samples-express-restful#569: Implements matching README normalization and RELEASES.md additions per the same specification referenced in #448.

Possibly related PRs

• chore(claude): rename and extend slash commands #446: Adds /pre-commit and /pre-release slash command implementations that this PR now references in the README Command Summary.
• chore(changelog): prepare CHANGELOG for 2.0.0 - centenario #422: Updates CHANGELOG and README release steps; directly related to this PR's new RELEASES.md release workflow documentation.
• docs(adr): add Architecture Decision Records (#372) #442: Introduces ADRs and ADR references in README documentation; related to this PR's consolidation of architecture explanation into a brief ADR-referencing callout.

🚥 Pre-merge checks | ✅ 2

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	Title follows Conventional Commits format (docs:), is under 80 characters (52 chars), and accurately describes the main changes: README restructuring and new RELEASES.md file addition.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/448-normalize-readme-structure

• 🛠️ sync documentation: Commit on current branch
• 🛠️ sync documentation: Create PR
• 🛠️ enforce http error handling: Commit on current branch
• 🛠️ enforce http error handling: Create PR
• 🛠️ idiomatic review: Commit on current branch
• 🛠️ idiomatic review: Create PR
• 🛠️ verify api contract: Commit on current branch
• 🛠️ verify api contract: Create PR

---

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: 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 `@README.md`:
- Around line 134-136: The diagram's arrow semantics conflict with the
documented layer rule: update either the diagram arrows (e.g., invert edges like
Services --> Controllers and Repositories --> Services to read Controller →
Service → Repository → Database) or change the callout text so "A → B means A is
depended on by B" to match the current graph; also add a sentence referencing
src/**/Controllers/*.cs that enforces the layer rule (Controllers must call
Services, not Repositories) so the README and diagram are consistent.

In `@RELEASES.md`:
- Around line 5-63: Add a required "Pre-release checklist" section into
RELEASES.md before the "Create and Push Tag" step that enumerates explicit
gating items (e.g., update CHANGELOG.md [Unreleased] into new release sections,
run tests/build in Release configuration, validate stadium name, run pre-commit
hooks/linters, verify Docker image tags and CI green) and require confirmation
that each item is completed before tagging; reference the CHANGELOG.md update
step and make "Update CHANGELOG.md [Unreleased]" an explicit checklist item to
be enforced as part of pre-commit checks or CI gating, so the release flow in
the "Automated CD Workflow" and tagging steps cannot proceed until the checklist
is completed.

🪄 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: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: c9011475-721b-4a50-b2bf-6fb02a814b06

📥 Commits

Reviewing files that changed from the base of the PR and between ed03238 and 12a1782.

📒 Files selected for processing (2)

• README.md
• RELEASES.md

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud