Add docs about pattern distribution and reuse

src/SUMMARY.md

@@ -27,3 +27,4 @@
     -   [How to Model an RPL Pattern](ch05-01-how-to-model-an-rpl-pattern.md)
     -   [How to Test an RPL Pattern](ch05-02-how-to-test-an-rpl-pattern.md)
 
+-   [Pattern Distribution](ch06-00-pattern-distribution.md)

src/ch01-00-getting-started-with-rpl.md

@@ -11,7 +11,5 @@
     - `RPL_PATS=/path/to/RPL/docs/patterns-pest cargo +nightly-2025-02-14 rpl` (using built-in RPL pattern definitions based on inline MIR)
     - `RUSTFLAGS="-Zinline-mir=false" RPL_PATS=/path/to/RPL/docs/patterns-pest cargo +nightly-2025-02-14 rpl` (using built-in RPL pattern definitions based on MIR)
 
-> We have the following plans for easing the usage of RPL:
->
-> -   Integration of standard patterns: Provide a set of commonly used patterns as part of RPL’s standard library.
-> -   Configuration-based pattern management: Introduce a `rpl.toml` configuration file to manage RPL patterns in a structured and centralized manner.
+RPL also supports configuration-based pattern management and Cargo-distributed pattern sets.
+See [Pattern Distribution](ch06-00-pattern-distribution.md) for design details and usage.

src/ch06-00-pattern-distribution.md

@@ -0,0 +1,107 @@
+# Pattern Distribution
+
+RPL patterns can be distributed and consumed through Cargo’s existing infrastructure.
+This keeps pattern sharing lightweight: patterns live in ordinary crates, are discovered through `cargo metadata`,
+and can be composed locally with project-specific patterns.
+
+This chapter covers the design intent, the on-disk configuration format, and the CLI workflow.
+
+## Design Overview
+
+RPL resolves pattern paths from two sources:
+
+- Local groups declared in `rpl.toml`, with paths relative to the file’s directory.
+- Remote groups published by a crate via `package.metadata.rpl` in its `Cargo.toml`.
+
+Remote groups are referenced with the `crate::group` syntax.
+When a remote group is selected, RPL runs `cargo metadata` for the current workspace,
+locates the named crate, and resolves the group entries relative to the crate root.
+No additional registry or RPL-specific package index is required.
+Consumers can freely compose imported groups with local groups and with other remote groups
+by selecting multiple groups in the desired order.
+
+## Publishing Patterns in a Crate
+
+To publish patterns, add metadata to the pattern crate’s `Cargo.toml`:
+
+```toml
+[package]
+name = "rpl-patterns"
+version = "0.1.0"
+
+[package.metadata.rpl]
+path = ["patterns"]
+
+[package.metadata.rpl.groups]
+all = ["."]
+```
+
+The fields mean:
+
+- `path`: optional list containing exactly one base directory, relative to the crate root. If omitted, `"."` is used.
+- `groups`: map from group name to a list of pattern paths, each relative to every base directory in `path`.
+
+In this example, `rpl-patterns::all` expands to `patterns/.` inside the crate.
+
+## Consuming Patterns with `rpl.toml`
+
+Place a `rpl.toml` file next to your project’s `Cargo.toml`:
+
+```toml
+[patterns]
+
+[[patterns.local]]
+name = "project"
+path = ["rpl/patterns", "rpl/extra"]
+
+[[patterns.remote]]
+name = "security"
+groups = ["rpl-patterns::all"]
+```
+
+Local groups are lists of paths relative to the directory that contains `rpl.toml`.
+Remote groups are lists of `crate::group` references from published crates.
+
+If you run `cargo rpl` with no `--patterns`, RPL will select `project` and then `security`
+in that order and set `RPL_PATS` accordingly.
+
+## Selecting Groups at Runtime
+
+You can override the default selection with `--patterns`:
+
+```bash
+cargo rpl --patterns project
+cargo rpl --patterns security
+cargo rpl --patterns rpl-patterns::all
+cargo rpl --patterns project --patterns rpl-patterns::all
+```
+
+Notes:
+
+- `--patterns` accepts a group name defined in `rpl.toml`, or a remote spec like `crate::group`.
+- Remote specs can be used even if `rpl.toml` is missing, as long as the crate is in the Cargo metadata graph.
+- If a selected group is unknown (and not a remote spec), RPL reports an error.
+
+## Cargo Integration Requirements
+
+Remote groups are resolved through `cargo metadata`, so the crate must be visible to Cargo.
+In practice, add the pattern crate as a dependency (often `dev-dependency`) of the workspace:
+
+```toml
+[dev-dependencies]
+rpl-patterns = "0.1"
+```
+
+If multiple crates share the same name in the metadata graph, RPL will refuse to guess.
+Keep the dependency graph unambiguous for pattern crates.
+
+## Environment Variable Interactions
+
+`RPL_PATS` is still supported and may be set manually:
+
+```bash
+RPL_PATS=path/to/patterns cargo rpl
+```
+
+If `RPL_PATS` is already set and you do not pass `--patterns`, RPL will not override it.
+Passing `--patterns` always recomputes and replaces the pattern list.