Split commons() into two

pkg-r/DESCRIPTION

@@ -34,6 +34,7 @@ Imports:
     jsonlite,
     knitr,
     later,
+    lifecycle,
     processx,
     promises (>= 1.5.0),
     R6,

pkg-r/NAMESPACE

@@ -1,5 +1,7 @@
 # Generated by roxygen2: do not edit by hand
 
+S3method(print,commons_text)
+export(agent)
 export(commons)
 export(commons_app)
 export(commons_server)

pkg-r/NEWS.md

@@ -1,6 +1,24 @@
 # commons (development version)
 
-* `commons()` gains a `mode` argument. With `mode = "trusted only"`, the agent answers only with trusted calculations. It never writes its own SQL or R, and it tells the user when no trusted calculation answers a question. These answers carry no provenance markers.
+* The `commons()` function was split into two. Calls to `commons()` previously looked like this:
+
+  ```r
+  commons <- commons(client, data_sources, semantic_layer, context_layer)
+  ```
+
+  The construction of the data structure that holds the data sources, semantic layer, and context layer and the construction of the agent harness that makes that information available to an LLM are now split into two pieces.
+
+  ```r
+  commons <- commons(data_sources = ..., semantic_layer = ..., context_layer = ...)
+  agent <- agent(client, commons = commons)
+  ```
+
+  We call that first data structure "the commons." The commons can be used to invoke trusted code and search trusted context directly from R and is intended for use with other coding agents. See `?commons()` to learn more. `agent()` returns what `commons()` used to return—a commons agent.
+
+  This transition was implemented backward-compatibly; existing calls to `commons()` will raise a deprecation warning with migration instructions.
+
+* `agent()` (formerly `commons()`) gains a `mode` argument. With `mode = "trusted only"`, the agent answers only with trusted calculations. It never writes its own SQL or R, and it tells the user when no trusted calculation answers a question. These answers carry no provenance markers.
+
 
 * `describe_table` reports complete table schemas and documentation without a sampled-row summary. DuckDB descriptions use database-native types. Snowflake and Databricks continue to use native metadata, while other DBI connections infer R column classes from five sampled rows, or zero rows in trusted-only mode (#319).