docs: guides + prepare v2.0.0 release

CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [2.0.0] - 2026-07-21
+
+### Changed
+
+- Nested CLI groups: `repo`, `dependabot`, and `environment` with subcommands.
+- `repo create` visibility via `--public` / `--private` / `--internal` (default public).
+- Moved argparse construction and command handlers into `parser.py`; `main.py` is a thin entrypoint.
+- Migrated uv development dependencies to PEP 735 `[dependency-groups]`.
+
+### Documentation
+
+- Added [CLI guide](docs/cli.md).
+- Added [Authentication](docs/authentication.md) guide (PAT scopes and token setup).
+- Expanded [configuration](docs/configuration.md) with `settings.toml` / `.secrets.toml` credential examples.
+- Documented the release process in [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## [1.0.3] - 2025-08-22
+
+Previous release on PyPI. See Git history and GitHub Releases for earlier notes.

CONTRIBUTING.md

@@ -43,11 +43,7 @@ uv pip list
 
 ## Authentication for local runs
 
-Export a GitHub PAT the same way end users do:
-
-```shell
-export GITHUB_AUTH_TOKEN="<github-auth-token>"
-```
+See [docs/authentication.md](docs/authentication.md) for PAT scopes and how to provide the token (`GITHUB_AUTH_TOKEN` or `.secrets.toml`).
 
 Run the CLI entrypoint:
 
@@ -68,6 +64,8 @@ just profile repo list --format json
 
 See [docs/configuration.md](docs/configuration.md) for environment variables, optional settings files, and Dynaconf tooling (`just dl` / `just dv`).
 
+CLI usage for end users: [docs/cli.md](docs/cli.md).
+
 ## Lint and format
 
 ```shell
@@ -91,6 +89,8 @@ just test
 
 ## Build and publish (maintainers)
 
+Local dry-run:
+
 ```shell
 just build-local
 just publish-local   # requires PYPI_TOKEN
@@ -102,6 +102,20 @@ Clean the uv cache:
 just cache
 ```
 
+### Release process
+
+Publishing to PyPI is triggered by creating a GitHub Release. The workflow is [`.github/workflows/release.yml`](.github/workflows/release.yml) (`uv build` + `uv publish` with Trusted Publishing).
+
+1. Ensure `main` is green (CI) and docs are up to date ([CLI guide](docs/cli.md), [configuration](docs/configuration.md)).
+2. Agree the SemVer bump (breaking CLI changes usually mean a major or an intentional minor while still Beta).
+3. Update `version` in [`pyproject.toml`](pyproject.toml).
+4. Move `[Unreleased]` notes in [`CHANGELOG.md`](CHANGELOG.md) into a new version section with today’s date.
+5. Open a PR for the version bump + changelog, merge to `main`.
+6. Create a GitHub Release for the new tag (for example `v2.0.0`) whose target is the merge commit on `main`.
+7. Confirm the **Python Publish Release** workflow succeeds on [PyPI](https://pypi.org/project/github-rest-cli/).
+
+Do not tag a release until the version in `pyproject.toml` matches the tag.
+
 ## Pull requests
 
 1. Create a branch from `main`

README.md

@@ -24,23 +24,9 @@ Requires Python 3.11.5 or newer.
 
 ## Authentication
 
-Create a [GitHub personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) and export it:
+See [Authentication](docs/authentication.md) for PAT scopes and how to set `GITHUB_AUTH_TOKEN` (or `.secrets.toml`).
 
-```shell
-export GITHUB_AUTH_TOKEN="<github-auth-token>"
-```
-
-Suggested classic PAT scopes:
-
-| Scope | Used for |
-| --- | --- |
-| `repo` | Private repos, create/delete, environments, Dependabot settings |
-| `public_repo` | Public repositories only (subset of `repo`) |
-| `delete_repo` | Deleting repositories (included in full `repo` on classic tokens) |
-
-Fine-grained tokens need repository access with permissions for Contents, Administration (create/delete), Environments, and Dependabot/security alerts as needed.
-
-For optional API URL overrides, settings files, and environments, see [Configuration](docs/configuration.md).
+For API URL overrides, settings files, and Dynaconf environments, see [Configuration](docs/configuration.md).
 
 ## Quick start
 
@@ -49,83 +35,20 @@ github-rest-cli --version
 github-rest-cli --help
 ```
 
-## Commands
-
-Top-level groups:
-
-```shell
-github-rest-cli repo --help
-github-rest-cli dependabot --help
-github-rest-cli environment --help
-```
-
-### Get a repository
-
-```shell
-github-rest-cli repo get --name my-repo
-github-rest-cli repo get --name my-repo --org my-org
-github-rest-cli repo get --name my-repo --format json
-```
-
-### List repositories
-
 ```shell
 github-rest-cli repo list
-github-rest-cli repo list --page 50 --sort pushed
-github-rest-cli repo list --role owner --format json
-```
-
-| Flag | Description | Default |
-| --- | --- | --- |
-| `-p` / `--page` | Number of results (`per_page`) | `20` |
-| `-s` / `--sort` | Sort field (e.g. `pushed`, `updated`, `created`) | `pushed` |
-| `-r` / `--role` | Filter by affiliation/role | unset |
-| `-f` / `--format` | Output format: `table` or `json` | `table` |
-
-### Create a repository
-
-```shell
-github-rest-cli repo create --name my-new-repo
+github-rest-cli repo get --name my-repo
 github-rest-cli repo create --name my-new-repo --private
-github-rest-cli repo create --name my-new-repo --org my-org
-github-rest-cli repo create --name my-new-repo --empty
-```
-
-### Delete a repository
-
-Prompts for confirmation unless `--yes` / `-y` is passed:
-
-```shell
-github-rest-cli repo delete --name my-repo
-github-rest-cli repo delete --name my-repo --org my-org
-github-rest-cli repo delete --name my-repo --yes
-```
-
-### Dependabot security updates
-
-```shell
-github-rest-cli dependabot enable --name my-repo
-github-rest-cli dependabot disable --name my-repo
-github-rest-cli dependabot enable --name my-repo --org my-org
-```
-
-### Deployment environments
-
-```shell
-github-rest-cli environment create --name my-repo --env production
-github-rest-cli environment create --name my-repo --env staging --org my-org
 ```
 
-## Output format
-
-`repo get` and `repo list` support:
+## Commands
 
-- `table` (default) — PrettyTable display
-- `json` — JSON string suitable for piping or scripting
+Full command reference: [CLI guide](docs/cli.md).
 
 ```shell
-github-rest-cli repo list --format json
-github-rest-cli repo get --name my-repo --format table
+github-rest-cli repo --help
+github-rest-cli dependabot --help
+github-rest-cli environment --help
 ```
 
 ## Contributing

docs/authentication.md

@@ -0,0 +1,53 @@
+# Authentication
+
+`github-rest-cli` authenticates to the GitHub REST API with a personal access token (PAT).
+
+## Create a token
+
+Create a [GitHub personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens).
+
+### Classic PAT scopes
+
+| Scope | Used for |
+| --- | --- |
+| `repo` | Private repos, create/delete, environments, Dependabot settings |
+| `public_repo` | Public repositories only (subset of `repo`) |
+| `delete_repo` | Deleting repositories (included in full `repo` on classic tokens) |
+
+### Fine-grained tokens
+
+Fine-grained tokens need repository access with permissions for Contents, Administration (create/delete), Environments, and Dependabot/security alerts as needed.
+
+## Provide the token
+
+### Environment variable (recommended)
+
+```shell
+export GITHUB_AUTH_TOKEN="<github-auth-token>"
+```
+
+### Settings file
+
+You can also set `AUTH_TOKEN` in `.secrets.toml` (gitignored). See [Configuration](configuration.md) for `settings.toml` / `.secrets.toml` layout and Dynaconf environments.
+
+```toml
+# .secrets.toml
+[default]
+AUTH_TOKEN = "ghp_your_token_here"
+```
+
+Never commit tokens. Prefer `.secrets.toml` or the environment variable.
+
+## Verify
+
+```shell
+github-rest-cli --version
+github-rest-cli repo list
+```
+
+If the token is missing or invalid, API calls fail with an authorization error.
+
+## See also
+
+- [Configuration](configuration.md) — env vars, settings files, `API_URL`
+- [CLI guide](cli.md) — commands and examples