Simplify the README synopsis; add development docs and AGENTS.md

AGENTS.md

@@ -0,0 +1,51 @@
+# AGENTS.md
+
+Guidance for AI coding agents working in this repository.
+
+## What this is
+
+`fm` is the FeedMob CLI: a Ruby gem packaged into native binaries with
+Tebako and distributed via Homebrew (the formula lives in `Formula/fm.rb` in
+this repo). See `README.md` for user-facing behavior.
+
+## Setup and verification
+
+```sh
+bundle install
+bundle exec exe/fm version     # run from the working tree
+bundle exec rake test          # minitest
+bundle exec rubocop --format simple
+```
+
+Tests and RuboCop must pass before opening a PR; CI also runs the
+release-packaging test matrix and Formula checks. Target Ruby is 3.2+
+(`.ruby-version` pins the exact patch).
+
+## Conventions
+
+- `# frozen_string_literal: true` in every Ruby file; follow existing style,
+  RuboCop config is the authority.
+- Runtime dependencies go in the gemspec and `packaging/Gemfile` only — the
+  release build packages just those. Dev/test dependencies stay in the root
+  `Gemfile`.
+- `Formula/fm.rb` is rendered by `script/render-homebrew-formula` during a
+  release. Never hand-edit it outside the release flow; it follows brew
+  style and is excluded from project RuboCop.
+- `FeedMob::CLI::VERSION` is bumped by the release workflow, not by hand.
+  Tests must derive expected versions from the constant, never hardcode one.
+
+## Security rules (hard requirements)
+
+- Credentials never appear in argv, logs, JSON output, error messages, or
+  test fixtures. Tests use sentinel tokens and loopback HTTP servers only.
+- Never touch the real macOS Keychain in tests — inject the fakes provided
+  through the `Keychain` constructor.
+- Base URLs are HTTPS-only; plain HTTP is allowed solely for loopback with
+  explicit `FEEDMOB_ALLOW_INSECURE_HTTP=1`.
+- Never overwrite a published tag or GitHub Release; the release pipeline
+  refuses to and so should you.
+
+## Releasing
+
+See `docs/release.md`. Releases are a manual workflow dispatch with
+auto-incremented versions; Formula PRs are always reviewed by a human.

README.md

@@ -5,16 +5,16 @@ credentials for Pixel and Time Off, verifies identity, and issues read-only
 API requests — with stable JSON output designed for scripts and automation.
 
 ```text
-fm [--json] doctor
-fm [--json] version
-fm [--json] pixel auth login [--token-stdin]
-fm [--json] pixel auth status
-fm [--json] pixel auth logout
-fm [--json] pixel request get <path>
-fm [--json] time-off auth login [--token-stdin]
-fm [--json] time-off auth status
-fm [--json] time-off auth logout
-fm [--json] time-off request get <path>
+fm doctor
+fm version
+fm pixel auth login [--token-stdin]
+fm pixel auth status
+fm pixel auth logout
+fm pixel request get <path>
+fm time-off auth login [--token-stdin]
+fm time-off auth status
+fm time-off auth logout
+fm time-off request get <path>
 ```
 
 ## Installation
@@ -114,5 +114,6 @@ a stable JSON envelope to stdout, including errors:
 
 ## Development and releasing
 
-See [docs/release.md](docs/release.md) for the Tebako/Homebrew release
+See [docs/development.md](docs/development.md) for local setup and testing,
+and [docs/release.md](docs/release.md) for the Tebako/Homebrew release
 pipeline and maintainer workflow.

docs/development.md

@@ -0,0 +1,51 @@
+# Development
+
+## Setup
+
+Requires Ruby 3.2+ (the repo pins `.ruby-version`; rbenv is used when
+available):
+
+```sh
+bundle install
+```
+
+Run the CLI from the working tree:
+
+```sh
+bundle exec exe/fm version
+bundle exec exe/fm doctor
+```
+
+Install it like an end user (isolated gem home under `~/.local`):
+
+```sh
+make install-local
+export PATH="$HOME/.local/bin:$PATH"
+```
+
+`PREFIX=/your/prefix make install-local` changes the install location.
+
+## Tests and lint
+
+```sh
+bundle exec rake test
+bundle exec rubocop --format simple
+```
+
+Both run in CI on every PR, along with the release-packaging test matrix
+(four native targets) and Formula checks. Platform-specific release tests
+skip automatically on non-matching hosts.
+
+## Layout
+
+- `lib/feedmob/cli/` — commands, credential storage (Keychain on macOS,
+  AES-256-GCM encrypted file elsewhere), HTTP client, JSON envelope
+- `exe/fm` — entry point
+- `script/` — release pipeline scripts (build, verify, publish, formula)
+- `packaging/` — pinned Tebako/Ruby release configuration and runtime Gemfile
+- `Formula/fm.rb` — Homebrew formula, rendered at release time
+
+## Releasing
+
+See [release.md](release.md). Versions auto-increment from the latest tag;
+publishing is a single manual workflow dispatch with a confirmation gate.