feat(group-blobs): pic kv ls/get --group + journey + docs (M4.3+M4.4)

- `pic kv ls --group` / `pic kv get --group` (mutually exclusive with --app)
  hit the M4 admin API; client group_kv_list/group_kv_get.
- collections journey: a script writes a shared KV value, the operator lists +
  fetches it via the admin API with no script.
- docs: §11.6 + CLAUDE.md record M3 quotas + M4 read-only admin API.

Completes M4.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

crates/picloud-cli/src/client.rs

@@ -1141,6 +1141,39 @@ impl Client {
         Ok(wrapped.value)
     }
 
+    /// §11.6 M4: a group's shared-KV collection.
+    /// `GET /api/v1/admin/groups/{id_or_slug}/kv?collection=…`
+    pub async fn group_kv_list(
+        &self,
+        group: &str,
+        collection: &str,
+        limit: u32,
+    ) -> Result<KvListPageDto> {
+        let (group, collection) = (seg(group), seg(collection));
+        let resp = self
+            .request(
+                Method::GET,
+                &format!("/api/v1/admin/groups/{group}/kv?collection={collection}&limit={limit}"),
+            )
+            .send()
+            .await?;
+        decode(resp).await
+    }
+
+    /// `GET /api/v1/admin/groups/{id_or_slug}/kv/{collection}/{key}`
+    pub async fn group_kv_get(&self, group: &str, collection: &str, key: &str) -> Result<Value> {
+        let (group, collection, key) = (seg(group), seg(collection), seg(key));
+        let resp = self
+            .request(
+                Method::GET,
+                &format!("/api/v1/admin/groups/{group}/kv/{collection}/{key}"),
+            )
+            .send()
+            .await?;
+        let wrapped: KvGetResponse = decode(resp).await?;
+        Ok(wrapped.value)
+    }
+
     // --- Queues (G2, read-only admin surface) -----------------------------
 
     /// `GET /api/v1/admin/apps/{id_or_slug}/queues`

crates/picloud-cli/src/cmds/kv.rs

@@ -7,16 +7,27 @@
 
 use std::io::Write;
 
-use anyhow::Result;
+use anyhow::{bail, Result};
 
 use crate::client::Client;
 use crate::config;
 use crate::output::{OutputMode, Table};
 
-pub async fn ls(app: &str, collection: &str, limit: u32, mode: OutputMode) -> Result<()> {
+pub async fn ls(
+    app: Option<&str>,
+    group: Option<&str>,
+    collection: &str,
+    limit: u32,
+    mode: OutputMode,
+) -> Result<()> {
     let creds = config::resolve()?;
     let client = Client::from_creds(&creds)?;
-    let page = client.kv_list(app, collection, limit).await?;
+    let page = match (app, group) {
+        (Some(a), None) => client.kv_list(a, collection, limit).await?,
+        // §11.6 M4: a group's shared-KV collection.
+        (None, Some(g)) => client.group_kv_list(g, collection, limit).await?,
+        _ => bail!("provide exactly one of --app or --group"),
+    };
     let mut table = Table::new(["key"]);
     for k in page.keys {
         table.row([k]);
@@ -31,10 +42,19 @@ pub async fn ls(app: &str, collection: &str, limit: u32, mode: OutputMode) -> Re
     Ok(())
 }
 
-pub async fn get(app: &str, collection: &str, key: &str) -> Result<()> {
+pub async fn get(
+    app: Option<&str>,
+    group: Option<&str>,
+    collection: &str,
+    key: &str,
+) -> Result<()> {
     let creds = config::resolve()?;
     let client = Client::from_creds(&creds)?;
-    let value = client.kv_get(app, collection, key).await?;
+    let value = match (app, group) {
+        (Some(a), None) => client.kv_get(a, collection, key).await?,
+        (None, Some(g)) => client.group_kv_get(g, collection, key).await?,
+        _ => bail!("provide exactly one of --app or --group"),
+    };
     // Always emit the JSON value (pretty) so it pipes cleanly into jq.
     let pretty = serde_json::to_string_pretty(&value).unwrap_or_else(|_| value.to_string());
     println!("{pretty}");

crates/picloud-cli/src/main.rs

@@ -315,19 +315,24 @@ struct ConfigArgs {
 
 #[derive(Subcommand)]
 enum KvCmd {
-    /// List keys in a collection.
+    /// List keys in a collection. Exactly one of `--app` (per-app KV) or
+    /// `--group` (a group's §11.6 shared KV).
     Ls {
+        #[arg(long, conflicts_with = "group")]
+        app: Option<String>,
         #[arg(long)]
-        app: String,
+        group: Option<String>,
         #[arg(long)]
         collection: String,
         #[arg(long, default_value_t = 100)]
         limit: u32,
     },
-    /// Fetch one key's value (printed as JSON).
+    /// Fetch one key's value (printed as JSON). `--app` or `--group`.
     Get {
+        #[arg(long, conflicts_with = "group")]
+        app: Option<String>,
         #[arg(long)]
-        app: String,
+        group: Option<String>,
         #[arg(long)]
         collection: String,
         key: String,
@@ -2083,18 +2088,20 @@ async fn main() -> ExitCode {
             cmd:
                 KvCmd::Ls {
                     app,
+                    group,
                     collection,
                     limit,
                 },
-        } => cmds::kv::ls(&app, &collection, limit, mode).await,
+        } => cmds::kv::ls(app.as_deref(), group.as_deref(), &collection, limit, mode).await,
         Cmd::Kv {
             cmd:
                 KvCmd::Get {
                     app,
+                    group,
                     collection,
                     key,
                 },
-        } => cmds::kv::get(&app, &collection, &key).await,
+        } => cmds::kv::get(app.as_deref(), group.as_deref(), &collection, &key).await,
     };
 
     match result {

crates/picloud-cli/tests/collections.rs

@@ -556,3 +556,93 @@ fn invoke_body(env: &common::TestEnv, id: &str) -> serde_json::Value {
     );
     serde_json::from_slice(&out.stdout).expect("invoke body is JSON")
 }
+
+/// §11.6 M4: the read-only operator admin API for a group's shared collections.
+/// A script writes to a shared KV collection; the operator then lists + fetches
+/// it through `pic kv ls --group` / `pic kv get --group` (no script).
+#[ignore = "needs DATABASE_URL pointing at a running Postgres"]
+#[test]
+fn operator_reads_shared_kv_via_admin_api() {
+    let Some(fx) = common::fixture_or_skip() else {
+        return;
+    };
+    let env = common::admin_env(fx);
+    let group = common::unique_slug("m4-grp");
+    let app = common::unique_slug("m4-app");
+
+    let _g = GroupGuard::new(&env.url, &env.token, &group);
+    common::pic_as(&env)
+        .args(["groups", "create", &group])
+        .assert()
+        .success();
+
+    let dir = manifest_dir();
+    let gmanifest =
+        format!("[group]\nslug = \"{group}\"\nname = \"M4\"\n\ncollections = [\"catalog\"]\n");
+    let gpath = dir.path().join("group.toml");
+    fs::write(&gpath, &gmanifest).unwrap();
+    common::pic_as(&env)
+        .args(["apply", "--file"])
+        .arg(&gpath)
+        .assert()
+        .success();
+
+    let _a = AppGuard::new(&env.url, &env.token, &app);
+    common::pic_as(&env)
+        .args(["apps", "create", &app, "--group", &group])
+        .assert()
+        .success();
+
+    // A script writes a value to the shared collection.
+    fs::write(
+        dir.path().join("scripts/w.rhai"),
+        r#"kv::shared_collection("catalog").set("op-key", #{ v: 42 }); "ok""#,
+    )
+    .unwrap();
+    common::pic_as(&env)
+        .args(["scripts", "deploy"])
+        .arg(dir.path().join("scripts/w.rhai"))
+        .args(["--app", &app, "--name", "w"])
+        .assert()
+        .success();
+    common::pic_as(&env)
+        .args(["scripts", "invoke", &app_script_id(&env, &app, "w")])
+        .assert()
+        .success();
+
+    // Operator lists the shared collection's keys via the admin API — no script.
+    let ls = String::from_utf8(
+        common::pic_as(&env)
+            .args(["kv", "ls", "--group", &group, "--collection", "catalog"])
+            .output()
+            .unwrap()
+            .stdout,
+    )
+    .unwrap();
+    assert!(
+        ls.contains("op-key"),
+        "kv ls --group must list the key:\n{ls}"
+    );
+
+    // Operator fetches the value.
+    let get = String::from_utf8(
+        common::pic_as(&env)
+            .args([
+                "kv",
+                "get",
+                "--group",
+                &group,
+                "--collection",
+                "catalog",
+                "op-key",
+            ])
+            .output()
+            .unwrap()
+            .stdout,
+    )
+    .unwrap();
+    assert!(
+        get.contains("42"),
+        "kv get --group must return the value:\n{get}"
+    );
+}