docs: improve README

README.md

@@ -1,67 +1,175 @@
 # ghactivities
 
-`ghactivities` is a Go CLI that collects GitHub activity for the authenticated user and writes compatible JSON event files.
+`ghactivities` is a Go CLI that exports your GitHub activity as JSON files. It authenticates as the current GitHub user, fetches supported event types from the GitHub GraphQL API, and writes machine-friendly output that can be archived, transformed, or imported into downstream tooling.
 
-## Supported events
+## What it collects
 
-- issues
-- issue comments
-- discussions
-- discussion comments
-- pull requests
-- pull request comments
-- commits
+`ghactivities` currently collects these event categories for the authenticated user:
 
-## Usage
+- issues you opened
+- issue comments you wrote
+- discussions you created
+- discussion comments you wrote
+- pull requests you opened
+- pull request comments you wrote
+- commits authored by you on default branches of repositories you contributed to during the selected time range
+
+Each JSON event includes the event type, creation timestamp, resource metadata, and repository owner/name/visibility.
+
+## Installation and build
+
+Run directly from the repository:
+
+```bash
+go run ./cmd/ghactivities --help
+```
+
+Build a local binary:
+
+```bash
+go build -o ./bin/ghactivities ./cmd/ghactivities
+```
+
+Then run it with:
 
 ```bash
-go run ./cmd/ghactivities --output ./ghactivities.json
+./bin/ghactivities --help
 ```
 
-Options:
+## Authentication
 
-- `--github-token`: GitHub access token. If omitted, `GITHUB_TOKEN` is used, then `gh auth token`.
-- `--output`: output path. Default: `./ghactivities.json`
-- `--since`: start date in ISO8601 format. Default: 2 weeks ago.
-- `--until`: end date in ISO8601 format. Default: now.
-- `--visibility`: `public`, `private`, or `all`. Default: `public`
-- `--max-length-size`: max JSON file size such as `1B`, `2K`, `2M`, `1.5M`. Default: `1M`
-- `--order`: `asc` or `desc`. Default: `asc`
+`ghactivities` resolves credentials in this order:
 
-If the JSON output exceeds `--max-length-size`, files are split as `ghactivities_1.json`, `ghactivities_2.json`, and so on.
+1. `--github-token`
+2. `GITHUB_TOKEN`
+3. `gh auth token`
 
-## Build
+If you want to rely on GitHub CLI authentication, make sure `gh auth login` has already been completed on your machine.
+
+## Quick start
+
+Export the last 2 weeks of public activity to the default file:
 
 ```bash
-go build -o ./bin/ghactivities ./cmd/ghactivities
+go run ./cmd/ghactivities
 ```
 
-## Test
+Write to a custom file:
 
 ```bash
-go test ./...
+go run ./cmd/ghactivities --output ./out/ghactivities.json
 ```
 
+Collect both public and private activity for a specific time window:
+
+```bash
+go run ./cmd/ghactivities \
+  --visibility all \
+  --since 2026-01-01T00:00:00Z \
+  --until 2026-01-31T23:59:59Z
+```
+
+Use an explicit token and reverse chronological ordering:
+
+```bash
+go run ./cmd/ghactivities \
+  --github-token "$GITHUB_TOKEN" \
+  --order desc
+```
+
+## CLI options
+
+```text
+--github-token      GitHub access token
+--output            Output file path (default: ./ghactivities.json)
+--since             Start date in ISO8601 format (default: 2 weeks ago)
+--until             End date in ISO8601 format (default: now)
+--visibility        Repository visibility: public, private, all (default: public)
+--max-length-size   Max output file size such as 1B, 2K, 2M (default: 1M)
+--order             Event order: asc, desc (default: asc)
+--help              Show help
+```
+
+Notes:
+
+- `--since` and `--until` must be valid RFC3339 / ISO8601 timestamps such as `2026-03-15T12:00:00Z`.
+- `--visibility private` limits results to repositories GitHub reports as private.
+- `--order asc` returns oldest-first output; `--order desc` returns newest-first output.
+
+## Output files and splitting
+
+By default, `ghactivities` writes a formatted JSON array to `./ghactivities.json`.
+
+If the rendered JSON exceeds `--max-length-size`, `ghactivities` automatically splits the result into numbered files that keep the same base name and extension:
+
+- `./ghactivities_1.json`
+- `./ghactivities_2.json`
+- `./ghactivities_3.json`
+
+For example:
+
+```bash
+go run ./cmd/ghactivities \
+  --output ./exports/activity.json \
+  --max-length-size 256K
+```
+
+This produces either `./exports/activity.json` or, when splitting is needed, files like `./exports/activity_1.json`, `./exports/activity_2.json`, and so on.
+
 ## Development setup
 
+This repository uses `mise` to install toolchain dependencies.
+
+Install the pinned tools:
+
 ```bash
 mise install
+```
+
+Install git hooks:
+
+```bash
 lefthook install
 ```
 
-After `lefthook install`, the `pre-commit` hook runs `gitleaks` against staged changes and blocks the commit if a secret is detected.
+Current development tooling includes:
+
+- `go` for building and testing `ghactivities`
+- `lefthook` for local git hook management
+- `gitleaks` for secret scanning in the pre-commit hook
+
+The configured `pre-commit` hook runs `gitleaks` against staged changes and blocks commits if potential secrets are detected.
+
+## Testing and validation
+
+Run the test suite:
+
+```bash
+go test ./...
+```
+
+Build the CLI:
+
+```bash
+go build -o ./bin/ghactivities ./cmd/ghactivities
+```
+
+Inspect the generated help text:
+
+```bash
+go run ./cmd/ghactivities --help
+```
+
+## Release automation
 
-## Release automation (Go release assets)
+GitHub Actions handles CI and release builds for `ghactivities`.
 
-- The release workflow builds binaries for configured platforms and attaches them to the GitHub Release as downloadable assets:
-- linux/amd64: ghactivities-linux-amd64
-- darwin/amd64: ghactivities-darwin-amd64
-- darwin/arm64: ghactivities-darwin-arm64
-- windows/amd64: ghactivities-windows-amd64.exe
-- These assets are uploaded automatically when a release is created on main.
+- `.github/workflows/ci.yml` runs `go test ./...`, builds `./bin/ghactivities`, and verifies the binary exists on pushes and pull requests to `main`.
+- `.github/workflows/release.yml` runs tests and builds release binaries when a GitHub Release is created.
+- Release assets are published for `linux/amd64`, `darwin/amd64`, `darwin/arm64`, and `windows/amd64`.
 
-## Design notes
+## Implementation notes
 
-- The CLI uses the GitHub GraphQL API to preserve the existing event categories and output shape.
-- Commit discovery first identifies contributed repositories from `contributionsCollection`, then reads default-branch commit history filtered by the authenticated viewer ID.
-- Comment collection intentionally follows the previous repository search semantics, including the parent-item search constraints used by the TypeScript implementation.
+- `ghactivities` uses the GitHub GraphQL API.
+- Commit discovery first identifies contributed repositories from the user's contributions collection, then reads authored commits from each repository's default branch within the requested date range.
+- Output is written as JSON with stable file naming that preserves the requested output base path.