feat(suppress): group-suppress warnings + ls + journey + docs (M1.5)

- dangling_suppress_warnings takes an ApplyOwner and walks the group's own
  chain (GROUP_CHAIN_LEVELS_CTE) for a group node; runs for both owners.
- GET /groups/{id}/suppressions + `pic suppress ls --group` (client + cmd +
  main.rs; --app/--group mutually exclusive).
- suppress journey: a child group declines a parent template for its subtree;
  suppress ls --group shows the marker. Docs §4.5 + CLAUDE.md move group-level
  suppression from Deferred to implemented.

Completes M1. (An unrelated pre-existing email_inbound dispatch-timing flake
passes in isolation.)

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

crates/picloud-cli/src/client.rs

@@ -1385,6 +1385,19 @@ impl Client {
             .await?;
         decode(resp).await
     }
+
+    /// §11 tail M1: a group's own suppressions (declined for its whole subtree).
+    pub async fn group_suppressions_list(&self, group_ident: &str) -> Result<Vec<SuppressionDto>> {
+        let ident = seg(group_ident);
+        let resp = self
+            .request(
+                Method::GET,
+                &format!("/api/v1/admin/groups/{ident}/suppressions"),
+            )
+            .send()
+            .await?;
+        decode(resp).await
+    }
 }
 
 /// One row of the §11 tail suppression report.

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

@@ -1,18 +1,23 @@
-//! `pic suppress ls --app <a>` — read-only view of an app's §11 tail
-//! per-app opt-outs: the inherited group templates it declines. App-only;
-//! authoring is declarative via the `[suppress]` block (`triggers = [...]`
-//! handler script names, `routes = [...]` paths).
+//! `pic suppress ls --app <a>` / `--group <g>` — read-only view of an owner's
+//! §11 tail opt-outs: the inherited group templates it declines. An app declines
+//! for itself; a group declines for its whole subtree (§11 tail M1). Authoring
+//! is declarative via the `[suppress]` block (`triggers = [...]` handler script
+//! names, `routes = [...]` paths).
 
-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, mode: OutputMode) -> Result<()> {
+pub async fn ls(app: Option<&str>, group: Option<&str>, mode: OutputMode) -> Result<()> {
     let creds = config::resolve()?;
     let client = Client::from_creds(&creds)?;
-    let items = client.suppressions_list(app).await?;
+    let items = match (app, group) {
+        (Some(a), None) => client.suppressions_list(a).await?,
+        (None, Some(g)) => client.group_suppressions_list(g).await?,
+        _ => bail!("provide exactly one of --app or --group"),
+    };
 
     let mut table = Table::new(["kind", "reference"]);
     for s in &items {

crates/picloud-cli/src/main.rs

@@ -587,10 +587,14 @@ enum CollectionsCmd {
 
 #[derive(Subcommand)]
 enum SuppressCmd {
-    /// List the inherited templates an app declines (§11 tail). App-only.
+    /// List the inherited templates an owner declines (§11 tail). Exactly one
+    /// of `--app` (declines for itself) or `--group` (declines for its whole
+    /// subtree, §11 tail M1).
     Ls {
+        #[arg(long, conflicts_with = "group")]
+        app: Option<String>,
         #[arg(long)]
-        app: String,
+        group: Option<String>,
     },
 }
 
@@ -2042,8 +2046,8 @@ async fn main() -> ExitCode {
             cmd: CollectionsCmd::Ls { group },
         } => cmds::collections::ls(&group, mode).await,
         Cmd::Suppress {
-            cmd: SuppressCmd::Ls { app },
-        } => cmds::suppress::ls(&app, mode).await,
+            cmd: SuppressCmd::Ls { app, group },
+        } => cmds::suppress::ls(app.as_deref(), group.as_deref(), mode).await,
         Cmd::Files {
             cmd:
                 FilesCmd::Ls {

crates/picloud-cli/tests/suppress.rs

@@ -201,3 +201,100 @@ fn app_suppresses_inherited_route_template() {
         "pruning the suppression must re-inherit the route"
     );
 }
+
+/// §11 tail M1: a CHILD group declares `[suppress]` for a template it inherits
+/// from its PARENT → every app in the child's subtree declines it; a `pic
+/// suppress ls --group` shows the marker.
+#[ignore = "needs DATABASE_URL pointing at a running Postgres"]
+#[test]
+fn group_suppresses_inherited_route_template_for_subtree() {
+    let Some(fx) = common::fixture_or_skip() else {
+        return;
+    };
+    let env = common::admin_env(fx);
+    let parent = common::unique_slug("gsup-p");
+    let child = common::unique_slug("gsup-c");
+
+    let _gp = GroupGuard::new(&env.url, &env.token, &parent);
+    let _gc = GroupGuard::new(&env.url, &env.token, &child);
+    common::pic_as(&env)
+        .args(["groups", "create", &parent])
+        .assert()
+        .success();
+    common::pic_as(&env)
+        .args(["groups", "create", &child, "--parent", &parent])
+        .assert()
+        .success();
+
+    // Parent handler + a route template binding it.
+    let dir = manifest_dir();
+    fs::write(
+        dir.path().join("scripts/phello.rhai"),
+        r#"log::info("parent route"); "ok""#,
+    )
+    .unwrap();
+    common::pic_as(&env)
+        .args(["scripts", "deploy"])
+        .arg(dir.path().join("scripts/phello.rhai"))
+        .args(["--group", &parent, "--name", "phello"])
+        .assert()
+        .success();
+    let _ps = ScriptGuard::new(
+        &env.url,
+        &env.token,
+        &group_script_id(&env, &parent, "phello"),
+    );
+    let pmanifest = format!(
+        "[group]\nslug = \"{parent}\"\nname = \"P\"\n\n\
+         [[routes]]\nscript = \"phello\"\npath = \"/phello\"\npath_kind = \"exact\"\n\
+         host_kind = \"any\"\n"
+    );
+    let ppath = dir.path().join("parent.toml");
+    fs::write(&ppath, &pmanifest).unwrap();
+    common::pic_as(&env)
+        .args(["apply", "--file"])
+        .arg(&ppath)
+        .assert()
+        .success();
+
+    // App under the CHILD group inherits the parent's route template.
+    let app = common::unique_slug("gsup-app");
+    let _a = AppGuard::new(&env.url, &env.token, &app);
+    common::pic_as(&env)
+        .args(["apps", "create", &app, "--group", &child])
+        .assert()
+        .success();
+    assert!(route_matches(&env, &app, "http://localhost/phello"));
+
+    // The CHILD group applies a [suppress] declining /phello → the whole child
+    // subtree stops serving it.
+    let cmanifest = format!(
+        "[group]\nslug = \"{child}\"\nname = \"C\"\n\n\
+         [suppress]\nroutes = [\"/phello\"]\n"
+    );
+    let cpath = dir.path().join("child.toml");
+    fs::write(&cpath, &cmanifest).unwrap();
+    common::pic_as(&env)
+        .args(["apply", "--file"])
+        .arg(&cpath)
+        .assert()
+        .success();
+    assert!(
+        !route_matches(&env, &app, "http://localhost/phello"),
+        "an app under the suppressing group must stop serving the inherited route"
+    );
+
+    // `pic suppress ls --group` shows the child's marker.
+    let ls = String::from_utf8(
+        common::pic_as(&env)
+            .args(["suppress", "ls", "--group", &child])
+            .output()
+            .unwrap()
+            .stdout,
+    )
+    .unwrap();
+    assert!(
+        ls.contains("route") && ls.contains("/phello"),
+        "suppress ls --group should list the route suppression:\n{ls}"
+    );
+}