Docs: clarify checkout-based development, Bundler usage, and test instructions

README.md

@@ -189,18 +189,31 @@ automatic --version
 
 ### From a checkout
 
+Use a checkout to try the current development version, change the source,
+develop a plugin or verify changes before a release:
+
 ```sh
 git clone https://github.com/id774/automaticruby.git
 cd automaticruby
 bundle install
 bundle exec bin/automatic --version
+bundle exec rake
 ```
 
+`bundle install` resolves the runtime and development dependencies declared by
+`Gemfile` and `automatic.gemspec`, and installs the gems needed to run and test
+the checkout. If the `bundle` command is unavailable, install Bundler first
+with `gem install bundler`.
+
 In a checkout, every `automatic` below becomes `bundle exec bin/automatic`.
+Use `bundle exec rake` to verify the development environment by running the
+test suite.
 
-Some plugins need a gem that is **not** installed with the framework —
-`fluent-logger`, `dalli`, `xml-simple` and a few others. Install one only if you
-use the plugin; the table is in [`doc/DEPLOYMENT.md`](doc/DEPLOYMENT.md).
+The core development setup does not install the optional `plugins` bundle
+group. Some plugins need their own gem or external service; install those only
+for the plugin being used or developed. Check the plugin catalogue in
+[`doc/PLUGINS.md`](doc/PLUGINS.md) and the dependency table in
+[`doc/DEPLOYMENT.md`](doc/DEPLOYMENT.md).
 
 ## 6. Quick start
 
@@ -558,7 +571,7 @@ Two rules worth knowing before you start:
 │   ├── fixtures/            Fixtures for the manual tests
 │   └── integration/         Recipes run by hand against real services
 ├── script/build             Runs what CI runs, plus the integration recipes
-├── vendor/                  Where `bundle config set --local path vendor/bundle` puts gems
+├── vendor/                  Legacy placeholder; the normal setup does not install gems here
 ├── doc/                     See below
 ├── automatic.gemspec        Hand-maintained
 ├── Gemfile

doc/DEPLOYMENT.md

@@ -32,16 +32,10 @@ nothing to stop.
   a version between them is supported and is simply not checked on every commit,
   and a Ruby newer than 4.0 is permitted rather than refused. See
   [`REQUIREMENTS.md`](REQUIREMENTS.md) section 20.
-- A build environment for native extensions, because `nokogiri` and `sqlite3`
-  may build from source:
-
-  ```sh
-  # Debian or Ubuntu
-  sudo apt install build-essential ruby-dev libsqlite3-dev
-
-  # macOS, with the Xcode command line tools installed
-  xcode-select --install
-  ```
+- A build environment may be needed if a dependency such as `nokogiri` or
+  `sqlite3` has to build a native extension on your platform. Start with the
+  normal installation below; install platform-specific build tools only if the
+  gem installation reports that they are required.
 
 - Optional gems for particular plugins, listed in the table under
   "Optional plugin dependencies" below. None is needed to install or to run a
@@ -68,15 +62,17 @@ git clone https://github.com/id774/automaticruby.git
 cd automaticruby
 bundle install
 bundle exec bin/automatic --version
+bundle exec rake
 ```
 
-`bundle install` installs into your default gem path. To keep it inside the
-checkout instead:
+`bundle install` resolves the runtime and development dependencies in `Gemfile`
+and `automatic.gemspec`. It installs what is needed to run the checkout and its
+test suite. If the `bundle` command is unavailable, install Bundler first with
+`gem install bundler`.
 
-```sh
-bundle config set --local path vendor/bundle
-bundle install
-```
+The default bundle does not install the optional `plugins` group. See
+"Optional plugin dependencies" below and [`PLUGINS.md`](PLUGINS.md) before
+installing anything for a particular plugin.
 
 Everything below that says `automatic` becomes `bundle exec bin/automatic` in a
 checkout.

doc/PLUGIN_DEVELOPMENT.md

@@ -3,6 +3,11 @@
 A plugin is a small Ruby class with `initialize` and `run`. It needs no registry,
 framework edit or dependency-injection container.
 
+To add or change a plugin in this repository, first follow the
+[source checkout setup](../README.md#from-a-checkout), including `bundle
+install` and the default test suite. User plugins under `~/.automatic` do not
+require a framework checkout.
+
 ## Naming and location
 
 The class name combines a category and a name. The file path separates them:

doc/QUICKSTART.md

@@ -93,8 +93,12 @@ Automatic Ruby runs once and exits; `cron` supplies the schedule.
 
 ## From a source checkout
 
+The normal installation above remains the quickest way to use Automatic Ruby.
+To try the development version or change the source, first follow
+[README's checkout setup](../README.md#from-a-checkout). Then run the same flow
+through the checkout's executable:
+
 ```sh
-bundle install
 bundle exec bin/automatic scaffold
 bundle exec bin/automatic -c ~/.automatic/config/example/feed2markdown.yml
 ```