docs: improve documentation (#121)

Author: maksym-arutyunyan

AGENTS.md

@@ -25,7 +25,7 @@ configuration files and code blocks stay tidy.
 - Use the Rust version pinned in `rust-toolchain.toml`.
 - Keep lists and manifest sections sorted; run `keepsorted` where annotated.
 - Update `CHANGELOG.md` for user-facing changes.
-- Do not modify `meta/SPECS.md` unless a human requests it.
+- Do not modify `docs/SPECS.md` unless a human requests it.
 - Markdown is formatted with `mdformat`; CI checks formatting.
 
 ## Reference

CHANGELOG.md

@@ -12,6 +12,7 @@ Adds quiet mode and skips binary files during recursive checks. Also drafts new
 - fix: correctly parse comments in `rust_derive` when string literals contain `//`
 - fix: correctly parse comments in `Cargo.toml` when string literals contain `#`
 - fix: correctly parse comments in Bazel files when string literals contain `#`
+- fix: bash 3.2 compatibility in `utils/exit_codes.bash`
 - fix: print stderr output when diff command fails
 - docs: draft meta guidelines for AI and contributors
 

README.md

@@ -11,7 +11,7 @@ cargo install keepsorted
 - [Documentation](https://docs.rs/keepsorted)
 - [Source code](https://github.com/maksym-arutyunyan/keepsorted)
 - [Issue tracker](https://github.com/maksym-arutyunyan/keepsorted/issues)
-- [Specs](meta/SPECS.md)
+- [Specs](docs/SPECS.md)
 
 ## Overview
 
@@ -178,9 +178,9 @@ a
 becomes
 
 ```codeowners
-# Team
-a
 # Lead
+a
+# Team
 b
 ```
 

meta/SPECS.md docs/SPECS.mdmeta/SPECS.md renamed to docs/SPECS.md

@@ -51,7 +51,7 @@ sorting strategies.
 - Source under `src/`.
 - Unit tests under `tests/`.
 - End-to-end tests using Bats in `e2e-tests/`.
-- Documentation in `docs/` and contributor guides in `meta/`.
+- Documentation in `docs/` and contributor guides in `docs/`.
 - Rust version pinned in `rust-toolchain.toml`; Cargo manages dependencies.
 
 ## Design notes

meta/SYSTEM.md docs/SYSTEM.mdmeta/SYSTEM.md renamed to docs/SYSTEM.md

@@ -15,7 +15,7 @@ Guides contributors through setup, development, testing, and releases.
 - `tests/` – Rust unit tests.
 - `e2e-tests/` – Bats-based end-to-end tests.
 - `docs/` – user documentation.
-- `meta/` – contributor guides (this folder).
+- `docs/` – contributor guides (this folder).
 - Temporary build output lives in `target/` and should not be committed.
 
 ## Coding conventions
@@ -32,7 +32,7 @@ Guides contributors through setup, development, testing, and releases.
 ## Documentation
 
 - Keep `README.md`, especially the "Getting Started" section, in sync with the
-  codebase and the specs in `meta/`.
+  codebase and the specs in `docs/`.
 
 ## Code quality
 
@@ -62,7 +62,7 @@ Guides contributors through setup, development, testing, and releases.
 ## Testing
 
 - Maintain unit tests in `tests/` and end-to-end tests in `e2e-tests/`.
-- Tests verify behaviour described in `meta/SPECS.md`, `meta/SYSTEM.md`, and
+- Tests verify behaviour described in `docs/SPECS.md`, `docs/SYSTEM.md`, and
   this workflow.
 - Bug fixes and new features require accompanying tests.
 - CI and local runs must pass all tests before merging.
@@ -87,14 +87,14 @@ A pull request is ready to merge when:
 ## Versioning & releases
 
 - Use Semantic Versioning (`MAJOR.MINOR.PATCH`).
-- Track version in `VERSION`, changes in `CHANGELOG.md`.
+- Track version in `Cargo.toml`, changes in `CHANGELOG.md`.
 - Group changelog entries by prefix: `feat`, `fix`, `refactor`, `test`, `docs`, `chore` (in that order). Keep original item order within each group.
 - Add a summary at the top of each release:
   - **Patch (`x.y.Z`)**: 1–2 lines on key fixes or internal changes.
   - **Minor (`x.Y.0`)**: Short paragraph on main new features since last minor.
   - **Major (`X.0.0`)**: Summary of major changes and any breaking updates.
 - Release PR:
-  - Only updates `VERSION`, `CHANGELOG.md`, and `README.md` if needed.
+  - Only updates `Cargo.toml` version, `CHANGELOG.md`, and `README.md` if needed.
   - Title: `chore(release): vX.Y.Z`
 - After merge:
   - CI tags the release and runs final checks.