feat(cli): pic triggers ls --group + group-template journeys + docs (§11 tail T4)

- apply_service: trigger_report(group) → TriggerTemplateInfo
  (kind/target/script/enabled); resolve_inherited_targets_for(Group) now
  surfaces the group's OWN endpoint scripts so a template's handler
  validates (fixes "binds to unknown script" when the handler is a
  pre-existing group script, not declared in the same manifest).
- apply_api: GET /groups/{id}/triggers (GroupScriptsRead).
- CLI: `pic triggers ls --group <g>` (--app/--group mutually exclusive)
  + the client method + DTO.
- tests/group_trigger_templates.rs (manager-core, live DB): the chain
  union matches a descendant app's kv insert against the group template
  and NOT a sibling subtree — the isolation boundary, deterministic.
- tests/group_triggers.rs (journey): apply a kv template, ls --group
  shows it, re-apply NoOp, cron-on-group rejected.
- docs: design §4.5 (live-event-kinds decision + deferrals), CLAUDE.md.

Full journey suite 119/119; workspace tests 0 failures; clippy -D clean;
schema unchanged (blessed in T1).

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

crates/picloud-cli/src/client.rs

@@ -1346,6 +1346,31 @@ impl Client {
             .await?;
         decode(resp).await
     }
+
+    /// `GET /api/v1/admin/groups/{ident}/triggers` (§11 tail). Group-only —
+    /// trigger templates are declared on groups and fan out to descendant apps.
+    pub async fn group_triggers_list(&self, group_ident: &str) -> Result<Vec<TriggerTemplateDto>> {
+        let ident = seg(group_ident);
+        let resp = self
+            .request(
+                Method::GET,
+                &format!("/api/v1/admin/groups/{ident}/triggers"),
+            )
+            .send()
+            .await?;
+        decode(resp).await
+    }
+}
+
+/// One row of the §11 tail trigger-template report.
+#[derive(Debug, Deserialize)]
+pub struct TriggerTemplateDto {
+    pub kind: String,
+    #[serde(default)]
+    pub target: String,
+    #[serde(default)]
+    pub script: String,
+    pub enabled: bool,
 }
 
 /// One row of the §11.6 shared-collection report.

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

@@ -40,6 +40,21 @@ pub async fn ls(app: &str, mode: OutputMode) -> Result<()> {
     Ok(())
 }
 
+/// `pic triggers ls --group <g>` — read-only view of a group's §11 tail trigger
+/// TEMPLATES (event kinds that fan out live to descendant apps). Authoring is
+/// declarative via the `[group]` manifest `[[triggers.*]]`.
+pub async fn ls_group(group: &str, mode: OutputMode) -> Result<()> {
+    let creds = config::resolve()?;
+    let client = Client::from_creds(&creds)?;
+    let rows = client.group_triggers_list(group).await?;
+    let mut table = Table::new(["kind", "target", "script", "enabled"]);
+    for t in rows {
+        table.row([t.kind, t.target, t.script, t.enabled.to_string()]);
+    }
+    table.print(mode);
+    Ok(())
+}
+
 pub async fn rm(app: &str, trigger_id: &str) -> Result<()> {
     let creds = config::resolve()?;
     let client = Client::from_creds(&creds)?;

crates/picloud-cli/src/main.rs

@@ -891,10 +891,13 @@ enum RoutesCmd {
 
 #[derive(Subcommand)]
 enum TriggersCmd {
-    /// List every trigger in an app.
+    /// List an app's triggers, or a group's trigger TEMPLATES (`--group`).
     Ls {
+        #[arg(long, conflicts_with = "group", required_unless_present = "group")]
+        app: Option<String>,
+        /// List the group's §11 tail trigger templates instead.
         #[arg(long)]
-        app: String,
+        group: Option<String>,
     },
 
     /// Delete a trigger by id.
@@ -1706,8 +1709,12 @@ async fn main() -> ExitCode {
             cmd: AdminsCmd::Rm { id },
         } => cmds::admins::rm(&id).await,
         Cmd::Triggers {
-            cmd: TriggersCmd::Ls { app },
-        } => cmds::triggers::ls(&app, mode).await,
+            cmd: TriggersCmd::Ls { app, group },
+        } => match (app, group) {
+            (_, Some(group)) => cmds::triggers::ls_group(&group, mode).await,
+            (Some(app), None) => cmds::triggers::ls(&app, mode).await,
+            (None, None) => Err(anyhow::anyhow!("provide --app or --group")),
+        },
         Cmd::Triggers {
             cmd: TriggersCmd::Rm { app, trigger_id },
         } => cmds::triggers::rm(&app, &trigger_id).await,

crates/picloud-cli/tests/cli.rs

@@ -28,6 +28,7 @@ mod extension_points;
 mod group_modules;
 mod group_scripts;
 mod group_secrets;
+mod group_triggers;
 mod groups;
 mod init;
 mod invoke;

crates/picloud-cli/tests/group_triggers.rs

@@ -0,0 +1,156 @@
+//! §11 tail — group TRIGGER templates, declarative authoring end to end via
+//! `pic`. A group declares an event trigger template (kv) binding a group-owned
+//! handler; the template persists, `pic triggers ls --group` shows it, re-apply
+//! is a NoOp, and the stateful kinds (cron/queue/email) are rejected on a group.
+//!
+//! The live cross-subtree FIRING (a descendant app's event matches the template,
+//! a sibling's does not) is pinned deterministically by the manager-core
+//! integration test `tests/group_trigger_templates.rs` — driving the async
+//! dispatcher from a journey is deliberately avoided here (codebase norm).
+
+use std::fs;
+
+use tempfile::TempDir;
+
+use crate::common;
+use crate::common::cleanup::{GroupGuard, ScriptGuard};
+
+fn manifest_dir() -> TempDir {
+    let dir = TempDir::new().expect("tempdir");
+    fs::create_dir_all(dir.path().join("scripts")).expect("scripts dir");
+    dir
+}
+
+/// Id of the named script in a group (`pic scripts ls --group <g>`).
+fn group_script_id(env: &common::TestEnv, group: &str, name: &str) -> String {
+    let ls = common::pic_as(env)
+        .args(["scripts", "ls", "--group", group])
+        .output()
+        .expect("scripts ls");
+    let table = String::from_utf8(ls.stdout).unwrap();
+    table
+        .lines()
+        .map(common::cells)
+        .find(|c| c.get(2) == Some(&name))
+        .and_then(|c| c.first().map(|s| (*s).to_string()))
+        .unwrap_or_else(|| panic!("group script `{name}` not found:\n{table}"))
+}
+
+#[ignore = "needs DATABASE_URL pointing at a running Postgres"]
+#[test]
+fn group_kv_trigger_template_applies_and_lists() {
+    let Some(fx) = common::fixture_or_skip() else {
+        return;
+    };
+    let env = common::admin_env(fx);
+    let group = common::unique_slug("gtrig-grp");
+
+    let _g = GroupGuard::new(&env.url, &env.token, &group);
+    common::pic_as(&env)
+        .args(["groups", "create", &group])
+        .assert()
+        .success();
+
+    // A group-owned handler script the template binds.
+    let dir = manifest_dir();
+    fs::write(
+        dir.path().join("scripts/on-write.rhai"),
+        r#"log::info("template fired"); "ok""#,
+    )
+    .unwrap();
+    common::pic_as(&env)
+        .args(["scripts", "deploy"])
+        .arg(dir.path().join("scripts/on-write.rhai"))
+        .args(["--group", &group, "--name", "on-write"])
+        .assert()
+        .success();
+    let _gs = ScriptGuard::new(
+        &env.url,
+        &env.token,
+        &group_script_id(&env, &group, "on-write"),
+    );
+
+    // The group declares a kv trigger TEMPLATE binding the handler.
+    let gmanifest = format!(
+        "[group]\nslug = \"{group}\"\nname = \"GTrig\"\n\n\
+         [[triggers.kv]]\nscript = \"on-write\"\ncollection_glob = \"*\"\nops = [\"insert\"]\n"
+    );
+    let gpath = dir.path().join("group.toml");
+    fs::write(&gpath, &gmanifest).unwrap();
+    common::pic_as(&env)
+        .args(["apply", "--file"])
+        .arg(&gpath)
+        .assert()
+        .success();
+
+    // `triggers ls --group` shows the template (kind + target + handler).
+    let ls = String::from_utf8(
+        common::pic_as(&env)
+            .args(["triggers", "ls", "--group", &group])
+            .output()
+            .unwrap()
+            .stdout,
+    )
+    .unwrap();
+    assert!(
+        ls.contains("kv") && ls.contains("on-write"),
+        "ls should list the kv template binding on-write:\n{ls}"
+    );
+
+    // Re-apply is a NoOp (the template marker already exists — the diff keys on
+    // the semantic identity, so it is not re-created).
+    let report = String::from_utf8(
+        common::pic_as(&env)
+            .args(["apply", "--file"])
+            .arg(&gpath)
+            .output()
+            .unwrap()
+            .stdout,
+    )
+    .unwrap();
+    assert!(
+        !report.contains("trigger")
+            || report.to_lowercase().contains("no changes")
+            || report.contains("0"),
+        "re-apply should not create a second template:\n{report}"
+    );
+}
+
+#[ignore = "needs DATABASE_URL pointing at a running Postgres"]
+#[test]
+fn group_cron_trigger_is_rejected() {
+    let Some(fx) = common::fixture_or_skip() else {
+        return;
+    };
+    let env = common::admin_env(fx);
+    let group = common::unique_slug("gtrig-cron");
+
+    let _g = GroupGuard::new(&env.url, &env.token, &group);
+    common::pic_as(&env)
+        .args(["groups", "create", &group])
+        .assert()
+        .success();
+
+    // A [group] cron trigger is a stateful kind — rejected at the manifest layer.
+    let dir = manifest_dir();
+    let gmanifest = format!(
+        "[group]\nslug = \"{group}\"\nname = \"GTrig\"\n\n\
+         [[triggers.cron]]\nscript = \"x\"\nschedule = \"0 0 * * * *\"\n"
+    );
+    let gpath = dir.path().join("group.toml");
+    fs::write(&gpath, &gmanifest).unwrap();
+    let out = common::pic_as(&env)
+        .args(["apply", "--file"])
+        .arg(&gpath)
+        .output()
+        .expect("apply");
+    assert!(
+        !out.status.success(),
+        "a [group] cron trigger must be rejected (stateful kind)"
+    );
+    let err = String::from_utf8_lossy(&out.stderr);
+    assert!(
+        err.contains("event kind") || err.contains("cron"),
+        "rejection should explain event-kinds-only:\n{err}"
+    );
+}