docs: add comprehensive configuration reference under docs/

- Add docs/ folder with an index plus topical pages for provisioners,
  installation, converge, cookbook resolution, paths, and target mode
- Document every option exposed via default_config across CincBase,
  CincInfra, CincSolo, CincApply, and CincTarget
- Replace the inline option list in README.md with links into docs/

Signed-off-by: Lance Albertson <lance@osuosl.org>

Author: ramereth

README.md

@@ -103,126 +103,22 @@ platforms:
 
 ### Configuration Options
 
-#### `product_name`
-
-- **Type:** String
-- **Default:** `cinc`
-- **Description:** The product to install. Set to `cinc` for Cinc Client or `cinc-workstation` for Cinc Workstation.
-
-#### `product_version`
-
-- **Type:** String
-- **Default:** `latest`
-- **Description:** The version of Cinc Client to install. Can be a specific version (e.g., `19.2.12`) or `latest`.
-
-#### `channel`
-
-- **Type:** String/Symbol
-- **Default:** `stable`
-- **Options:** `stable`, `current`
-- **Description:** The release channel to install from.
-
-#### `install_strategy`
-
-- **Type:** String
-- **Default:** `once`
-- **Options:** `once`, `always`
-- **Description:** When to install Cinc. `once` only installs if not present, `always` reinstalls on every converge.
-
-#### `download_url`
-
-- **Type:** String
-- **Default:** none
-- **Description:** Override the download URL for custom package locations or air-gapped environments.
-
-#### `checksum`
-
-- **Type:** String
-- **Default:** none
-- **Description:** SHA256 checksum to verify the downloaded package. Used with `download_url`.
-
-#### `platform`, `platform_version`, `architecture`
-
-- **Type:** String
-- **Default:** Auto-detected
-- **Description:** Explicitly specify platform details for package selection.
-
-#### `run_list`
-
-- **Type:** Array
-- **Default:** `[]`
-- **Description:** The Cinc run list to execute.
-
-#### `attributes`
-
-- **Type:** Hash
-- **Default:** `{}`
-- **Description:** Node attributes to set during the converge.
-
-#### `log_level`
-
-- **Type:** String
-- **Default:** `auto`
-- **Description:** Cinc log level. Set to `debug` for verbose output, or `auto` to let Cinc decide.
-
-#### `log_file`
-
-- **Type:** String
-- **Default:** none
-- **Description:** Path to write the Cinc log file on the test instance.
-
-#### `multiple_converge`
-
-- **Type:** Integer
-- **Default:** `1`
-- **Description:** Number of times to run converge. Useful with `enforce_idempotency`.
-
-#### `enforce_idempotency`
-
-- **Type:** Boolean
-- **Default:** `false`
-- **Description:** When `true`, fails the run if the second converge makes changes. Requires `multiple_converge` >= 2.
-
-#### `deprecations_as_errors`
-
-- **Type:** Boolean
-- **Default:** `false`
-- **Description:** Treat Cinc deprecation warnings as errors.
-
-### Policyfile Support
-
-kitchen-cinc auto-detects `Policyfile.rb` in your cookbook directory and uses it for dependency resolution. You can also configure it explicitly:
-
-```yaml
-provisioner:
-  name: cinc_infra
-  policyfile_path: path/to/Policyfile.rb
-  policy_group: local
-  always_update_cookbooks: true
-```
-
-### Berkshelf Support
-
-If no Policyfile is found, kitchen-cinc will fall back to Berkshelf if a `Berksfile` is present:
-
-```yaml
-provisioner:
-  name: cinc_infra
-  berksfile_path: path/to/Berksfile
-  always_update_cookbooks: true
-```
-
-### Path Configuration
-
-All paths are auto-calculated if not specified:
-
-- `data_path` — Path to data directory
-- `data_bags_path` — Path to data bags
-- `environments_path` — Path to environments
-- `nodes_path` — Path to node definitions
-- `roles_path` — Path to roles
-- `clients_path` — Path to clients
-- `encrypted_data_bag_secret_key_path` — Path to encryption key
+Every option exposed by the provisioners is documented under
+[`docs/`](docs/README.md):
+
+- [Provisioners](docs/provisioners.md) — overview of `cinc_infra`,
+  `cinc_zero`, `cinc_solo`, `cinc_apply`, and `cinc_target`.
+- [Installation options](docs/installation.md) — `product_name`,
+  `product_version`, `channel`, `install_strategy`, `download_url`,
+  `checksum`, proxies, and the legacy omnibus options.
+- [Converge options](docs/converge.md) — `run_list`, `attributes`,
+  logging, `multiple_converge`, `enforce_idempotency`, `client_rb` /
+  `solo_rb`, Chef Zero host/port, and more.
+- [Cookbook resolution](docs/cookbook-resolution.md) — Policyfile and
+  Berkshelf integration.
+- [Paths](docs/paths.md) — sandbox, on-instance, and binary paths.
+- [Target mode](docs/target-mode.md) — extra requirements and option
+  overrides for `cinc_target`.
 
 ## Development
 

docs/README.md

@@ -0,0 +1,34 @@
+# kitchen-cinc Documentation
+
+Reference documentation for every configuration option exposed by the
+kitchen-cinc provisioners.
+
+## Contents
+
+- [Provisioners](provisioners.md) — overview of the available provisioner
+  classes (`cinc_infra`, `cinc_zero`, `cinc_solo`, `cinc_apply`,
+  `cinc_target`) and when to use each.
+- [Installation options](installation.md) — controls how Cinc Client is
+  downloaded and installed on the test instance (product, channel,
+  version, download URL, omnibus options, proxies).
+- [Converge options](converge.md) — controls how Cinc is invoked during
+  the converge phase (run list, attributes, logging, multiple converges,
+  idempotency, JSON attributes, Chef Zero host/port, etc.).
+- [Cookbook resolution](cookbook-resolution.md) — Policyfile and
+  Berkshelf integration, cookbook upload behavior.
+- [Paths](paths.md) — sandbox layout, on-instance paths, and the path
+  defaults for Cinc binaries (`cinc-client`, `cinc-solo`, `cinc-apply`).
+- [Target mode](target-mode.md) — extra requirements and options for the
+  `cinc_target` provisioner.
+
+## Conventions
+
+Every option below is documented with:
+
+- **Type** — Ruby type accepted (`String`, `Integer`, `Boolean`,
+  `Hash`, `Array`, `Symbol`).
+- **Default** — value used when the option is not set in `kitchen.yml`.
+  `auto` means the value is derived at runtime; `none` means `nil`.
+- **Description** — what the option does and any relevant constraints.
+
+Options marked **(advanced)** are rarely needed in normal use.

docs/converge.md

@@ -0,0 +1,151 @@
+# Converge Options
+
+These options control how Cinc Client is invoked during the converge
+phase. Most apply to every provisioner; provisioner-specific notes are
+called out where relevant.
+
+## Run list and attributes
+
+### `run_list`
+
+- **Type:** Array
+- **Default:** `[]`
+- The Cinc run list to execute. Items can be recipe names
+  (`recipe[my_cookbook::default]`) or role names.
+
+### `attributes`
+
+- **Type:** Hash
+- **Default:** `{}`
+- Node attributes to set during the converge. Merged into the JSON
+  attributes file or the `client.rb`/`solo.rb` config depending on
+  provisioner.
+
+### `named_run_list` (`cinc_infra` / `cinc_zero` / `cinc_target`)
+
+- **Type:** Hash
+- **Default:** `{}`
+- Selects a named run list defined in a Policyfile.
+
+### `policy_group`
+
+- **Type:** String
+- **Default:** none
+- Policy group used when resolving a Policyfile. See
+  [cookbook-resolution.md](cookbook-resolution.md).
+
+### `json_attributes` (`cinc_infra` / `cinc_zero` / `cinc_target`)
+
+- **Type:** Boolean
+- **Default:** `true`
+- When `true`, the provisioner writes a `dna.json` file to the sandbox
+  and passes `--json-attributes` to `cinc-client`.
+
+## Logging
+
+### `log_level`
+
+- **Type:** String
+- **Default:** `"auto"` (or `"debug"` if Test Kitchen debug is on)
+- Cinc log level. Common values: `"auto"`, `"info"`, `"warn"`,
+  `"debug"`, `"trace"`.
+
+### `log_file`
+
+- **Type:** String
+- **Default:** none
+- Path to write the Cinc log file on the test instance. When set, the
+  provisioner passes `--logfile <path>` to `cinc-client`.
+
+### `profile_ruby`
+
+- **Type:** Boolean
+- **Default:** `false`
+- When `true`, passes `--profile-ruby` to `cinc-client`.
+
+### `slow_resource_report` (advanced, `cinc_infra` / `cinc_zero` / `cinc_target`)
+
+- **Type:** Boolean or Integer
+- **Default:** none
+- When set, passes `--slow-report` (or `--slow-report N` if an integer
+  is given) to `cinc-client`.
+
+## Multiple converges and idempotency
+
+### `multiple_converge`
+
+- **Type:** Integer
+- **Default:** `1`
+- Number of times to invoke Cinc per converge. Useful in combination
+  with `enforce_idempotency` to assert that a second run is a no-op.
+
+### `enforce_idempotency`
+
+- **Type:** Boolean
+- **Default:** `false`
+- When `true`, the final converge uses an alternate `client.rb` that
+  fails the run if any resource reports `:updated`. Pair with
+  `multiple_converge: 2` (or higher).
+
+### `retry_on_exit_code`
+
+- **Type:** Array of Integer
+- **Default:** `[35, 213]`
+- Exit codes that Test Kitchen should treat as a successful retry
+  signal (used by Cinc reboot handling).
+
+### `deprecations_as_errors`
+
+- **Type:** Boolean
+- **Default:** `false`
+- Sets `treat_deprecation_warnings_as_errors true` in the rendered
+  `client.rb` / `solo.rb` so any deprecation warning fails the run.
+
+## Custom config injection
+
+### `client_rb` (`cinc_infra` / `cinc_zero` / `cinc_target`)
+
+- **Type:** Hash
+- **Default:** `{}`
+- Extra entries merged into the rendered `client.rb`. Keys become
+  config attribute names; values are formatted with Ruby `inspect`
+  semantics. Example:
+
+  ```yaml
+  provisioner:
+    name: cinc_infra
+    client_rb:
+      chef_server_url: https://my-chef-server.example.com/organizations/test
+      ssl_verify_mode: :verify_peer
+  ```
+
+### `solo_rb` (`cinc_solo`)
+
+- **Type:** Hash
+- **Default:** `{}`
+- Extra entries merged into the rendered `solo.rb`. Same semantics as
+  `client_rb`.
+
+### `config_path`
+
+- **Type:** String
+- **Default:** none
+- Path to a `config.rb` that `ChefConfig::WorkstationConfigLoader`
+  should load on startup, before any provisioner code runs. Lets you
+  share workstation-level config (proxy settings, etc.) with
+  kitchen-cinc.
+
+## Chef Zero networking (`cinc_infra` / `cinc_zero` / `cinc_target`)
+
+### `cinc_zero_host`
+
+- **Type:** String
+- **Default:** `nil`
+- Value passed to `--chef-zero-host`. Leave unset for the Cinc default
+  bind address.
+
+### `cinc_zero_port`
+
+- **Type:** Integer
+- **Default:** `8889`
+- Value passed to `--chef-zero-port`.