feat(cli): collections manifest + ls + journeys; rename to kv::shared_collection (§11.6 C5)

Finish the §11.6 KV slice: declarative authoring, read-only inspection, the
runtime journey, and docs — plus a forced SDK-name fix.

- SDK name: `shared` is a Rhai RESERVED keyword, so `kv::shared(...)` is a parse
  error. Renamed the handle constructor to `kv::shared_collection(...)`
  (keeps the user's "shared" intent; unambiguous). Updated everywhere.
- CLI manifest: `collections = [...]` on `[group]` only (ManifestApp has no such
  field + deny_unknown_fields → an app manifest carrying it is a hard error);
  Manifest::collections() accessor; build_bundle emits it.
- plan/apply: a `collection` row group in `pic plan`; created/deleted counts in
  the apply summary; collections threaded through PlanDto/NodePlanDto/
  ApplyReportDto.
- read-only `pic collections ls --group` → GET /admin/groups/{id}/collections
  (viewer+), backed by ApplyService::collection_report + CollectionInfo.
- journey: a group declares `catalog`; app A writes, app B (same subtree) reads
  it back; a sibling-subtree app gets CollectionNotShared; `collections ls` +
  re-apply NoOp. Full suite 114/114.
- docs: groups-and-project-tool §11.6 (KV-only MVP shipped + deferrals),
  sdk-shape.md (the shared-collection handle + trust model), CLAUDE.md.

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

crates/picloud-cli/src/client.rs

@@ -1332,6 +1332,26 @@ impl Client {
             .await?;
         decode(resp).await
     }
+
+    /// `GET /api/v1/admin/groups/{ident}/collections` (§11.6). Group-only —
+    /// shared collections are declared on groups.
+    pub async fn collections_list(&self, group_ident: &str) -> Result<Vec<CollectionInfoDto>> {
+        let ident = seg(group_ident);
+        let resp = self
+            .request(
+                Method::GET,
+                &format!("/api/v1/admin/groups/{ident}/collections"),
+            )
+            .send()
+            .await?;
+        decode(resp).await
+    }
+}
+
+/// One row of the §11.6 shared-collection report.
+#[derive(Debug, Deserialize)]
+pub struct CollectionInfoDto {
+    pub name: String,
 }
 
 // ---------- DTOs (CLI-local, wire-shape-matched) ----------
@@ -1351,6 +1371,8 @@ pub struct PlanDto {
     pub vars: Vec<ChangeDto>,
     #[serde(default)]
     pub extension_points: Vec<ChangeDto>,
+    #[serde(default)]
+    pub collections: Vec<ChangeDto>,
     /// Fingerprint of the live state this plan was computed against; carried
     /// in `.picloud/` and replayed to `apply` for the bound-plan check.
     #[serde(default)]
@@ -1391,6 +1413,8 @@ pub struct NodePlanDto {
     pub vars: Vec<ChangeDto>,
     #[serde(default)]
     pub extension_points: Vec<ChangeDto>,
+    #[serde(default)]
+    pub collections: Vec<ChangeDto>,
 }
 
 /// Response of `POST .../apply`: counts of what changed.
@@ -1423,6 +1447,10 @@ pub struct ApplyReportDto {
     #[serde(default)]
     pub extension_points_deleted: u32,
     #[serde(default)]
+    pub collections_created: u32,
+    #[serde(default)]
+    pub collections_deleted: u32,
+    #[serde(default)]
     pub warnings: Vec<String>,
 }
 

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

@@ -91,6 +91,13 @@ pub async fn run(
                 "+{} -{}",
                 report.extension_points_created, report.extension_points_deleted
             ),
+        )
+        .field(
+            "collections",
+            format!(
+                "+{} -{}",
+                report.collections_created, report.collections_deleted
+            ),
         );
     for w in &report.warnings {
         block.field("warning", w.clone());
@@ -165,6 +172,13 @@ pub async fn run_tree(
                 "+{} -{}",
                 report.extension_points_created, report.extension_points_deleted
             ),
+        )
+        .field(
+            "collections",
+            format!(
+                "+{} -{}",
+                report.collections_created, report.collections_deleted
+            ),
         );
     for w in &report.warnings {
         block.field("warning", w.clone());

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

@@ -0,0 +1,23 @@
+//! `pic collections ls --group <g>` — read-only view of a group's §11.6 shared
+//! KV collections. Group-only (shared collections are owned by groups);
+//! authoring is declarative via the `[group]` manifest `collections = [...]`.
+//! Scripts read/write them with `kv::shared_collection("name")`.
+
+use anyhow::Result;
+
+use crate::client::Client;
+use crate::config;
+use crate::output::{OutputMode, Table};
+
+pub async fn ls(group: &str, mode: OutputMode) -> Result<()> {
+    let creds = config::resolve()?;
+    let client = Client::from_creds(&creds)?;
+    let items = client.collections_list(group).await?;
+
+    let mut table = Table::new(["name"]);
+    for c in &items {
+        table.row([c.name.clone()]);
+    }
+    table.print(mode);
+    Ok(())
+}

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

@@ -3,6 +3,7 @@ pub mod api_keys;
 pub mod apply;
 pub mod apps;
 pub mod apps_domains;
+pub mod collections;
 pub mod config;
 pub mod dead_letters;
 pub mod extension_points;

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

@@ -64,13 +64,14 @@ fn render_tree(plan: &TreePlanDto, mode: OutputMode) {
     let mut table = Table::new(["node", "kind", "op", "resource", "detail"]);
     for n in &plan.nodes {
         let node = format!("{}:{}", n.kind, n.slug);
-        let groups: [(&str, &Vec<ChangeDto>); 6] = [
+        let groups: [(&str, &Vec<ChangeDto>); 7] = [
             ("script", &n.scripts),
             ("route", &n.routes),
             ("trigger", &n.triggers),
             ("secret", &n.secrets),
             ("var", &n.vars),
             ("extension_point", &n.extension_points),
+            ("collection", &n.collections),
         ];
         for (rk, changes) in groups {
             for c in changes {
@@ -162,6 +163,7 @@ pub fn build_bundle(manifest: &Manifest, base_dir: &Path) -> Result<Value> {
         "secrets": manifest.secrets.names,
         "vars": vars,
         "extension_points": manifest.extension_points(),
+        "collections": manifest.collections(),
     }))
 }
 
@@ -176,13 +178,14 @@ fn tagged(kind: &str, spec: impl Serialize) -> Result<Value> {
 
 fn render(plan: &PlanDto, mode: OutputMode) {
     let mut table = Table::new(["kind", "op", "resource", "detail"]);
-    let groups: [(&str, &Vec<ChangeDto>); 6] = [
+    let groups: [(&str, &Vec<ChangeDto>); 7] = [
         ("script", &plan.scripts),
         ("route", &plan.routes),
         ("trigger", &plan.triggers),
         ("secret", &plan.secrets),
         ("var", &plan.vars),
         ("extension_point", &plan.extension_points),
+        ("collection", &plan.collections),
     ];
     for (kind, changes) in groups {
         for c in changes {

crates/picloud-cli/src/main.rs

@@ -162,6 +162,15 @@ enum Cmd {
         cmd: ExtensionPointsCmd,
     },
 
+    /// Shared group collections (§11.6) — read-only view of the KV collection
+    /// names a group offers as cross-app-shared. Authored declaratively via the
+    /// `[group]` manifest `collections = [...]`; scripts read/write them with
+    /// `kv::shared_collection("name")`.
+    Collections {
+        #[command(subcommand)]
+        cmd: CollectionsCmd,
+    },
+
     /// Files inspection — list a collection's blobs, download bytes, or
     /// delete a file. Read + delete only; writes go through scripts.
     Files {
@@ -558,6 +567,16 @@ enum ExtensionPointsCmd {
     },
 }
 
+#[derive(Subcommand)]
+enum CollectionsCmd {
+    /// List the shared collections a group declares (§11.6). Group-only —
+    /// shared collections are owned by groups, not apps.
+    Ls {
+        #[arg(long)]
+        group: String,
+    },
+}
+
 #[derive(Subcommand)]
 enum ScriptsCmd {
     /// List scripts. With `--app`, scoped to one app; with `--group`, a
@@ -1985,6 +2004,9 @@ async fn main() -> ExitCode {
         Cmd::ExtensionPoints {
             cmd: ExtensionPointsCmd::Ls { app, group },
         } => cmds::extension_points::ls(app.as_deref(), group.as_deref(), mode).await,
+        Cmd::Collections {
+            cmd: CollectionsCmd::Ls { group },
+        } => cmds::collections::ls(&group, mode).await,
         Cmd::Files {
             cmd:
                 FilesCmd::Ls {

crates/picloud-cli/src/manifest.rs

@@ -111,6 +111,17 @@ impl Manifest {
         }
     }
 
+    /// This node's declared shared group-collection names (§11.6). Authored on
+    /// `[group]` nodes only — an `[app]` manifest carrying `collections` is a
+    /// hard parse error (`ManifestApp` has no such field + `deny_unknown_fields`).
+    #[must_use]
+    pub fn collections(&self) -> &[String] {
+        match &self.group {
+            Some(g) => &g.collections,
+            None => &[],
+        }
+    }
+
     /// Load and parse the manifest at `path`.
     pub fn load(path: &Path) -> Result<Self> {
         let body =
@@ -238,6 +249,13 @@ pub struct ManifestGroup {
     /// See [`ManifestApp::extension_points`]. A key of the `[group]` table.
     #[serde(default, skip_serializing_if = "Vec::is_empty")]
     pub extension_points: Vec<String>,
+    /// `collections = ["catalog", …]` (§11.6) — shared KV collection names this
+    /// group offers as cross-app-shared (read by any app in the subtree,
+    /// written by an authenticated editor+). Group-only: there is no
+    /// `collections` key on `[app]`. The data lives in `group_kv_entries`;
+    /// pruning a name removes the declaration, not the data.
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub collections: Vec<String>,
 }
 
 #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]