feat(cli): pic routes ls --group + group-route journey + docs (§11 tail R5)

Visibility + end-to-end coverage + docs for group route templates.

- ApplyService::route_report(Group) → GET /api/v1/admin/groups/{id}/routes
  (viewer-tier GroupScriptsRead), surfacing a group's own route templates
  (method, host, path, handler script, dispatch, enabled).
- CLI: `pic routes ls --group <g>` (the script-id positional now conflicts
  with --group), client `group_routes_list` + RouteTemplateDto.
- Journey `group_routes.rs`: a group declares a `[[routes]]` template
  binding a group handler; a DESCENDANT app serves it (via `routes match`
  against the live RouteTable), a SIBLING-subtree app does not, `routes ls
  --group` shows it, re-apply is a NoOp. Shadowing + isolation are
  additionally pinned at the repo layer by group_route_templates.rs.
- Update the manifest unit test: a [group] now accepts route templates and
  rejects only the stateful trigger kinds.
- Docs: design §4.5 (the live route-template model + full-live
  invalidation + nearest-wins shadowing + deferrals), CLAUDE.md focus.

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

crates/picloud-cli/src/client.rs

@@ -1360,6 +1360,17 @@ impl Client {
             .await?;
         decode(resp).await
     }
+
+    /// `GET /api/v1/admin/groups/{ident}/routes` (§11 tail). Group-only — route
+    /// templates are declared on groups and inherited by descendant apps.
+    pub async fn group_routes_list(&self, group_ident: &str) -> Result<Vec<RouteTemplateDto>> {
+        let ident = seg(group_ident);
+        let resp = self
+            .request(Method::GET, &format!("/api/v1/admin/groups/{ident}/routes"))
+            .send()
+            .await?;
+        decode(resp).await
+    }
 }
 
 /// One row of the §11 tail trigger-template report.
@@ -1373,6 +1384,24 @@ pub struct TriggerTemplateDto {
     pub enabled: bool,
 }
 
+/// One row of the §11 tail route-template report.
+#[derive(Debug, Deserialize)]
+pub struct RouteTemplateDto {
+    #[serde(default)]
+    pub method: String,
+    #[serde(default)]
+    pub host: String,
+    #[serde(default)]
+    pub path_kind: String,
+    #[serde(default)]
+    pub path: String,
+    #[serde(default)]
+    pub script: String,
+    #[serde(default)]
+    pub dispatch: String,
+    pub enabled: bool,
+}
+
 /// One row of the §11.6 shared-collection report.
 #[derive(Debug, Deserialize)]
 pub struct CollectionInfoDto {

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

@@ -35,6 +35,37 @@ pub async fn ls(script_id: &str, mode: OutputMode) -> Result<()> {
     Ok(())
 }
 
+/// `pic routes ls --group <g>` — read-only view of a group's §11 tail route
+/// TEMPLATES (inherited live by every descendant app). Authoring is declarative
+/// via the `[group]` manifest `[[routes]]`.
+pub async fn ls_group(group: &str, mode: OutputMode) -> Result<()> {
+    let creds = config::resolve()?;
+    let client = Client::from_creds(&creds)?;
+    let rows = client.group_routes_list(group).await?;
+    let mut table = Table::new([
+        "method",
+        "host",
+        "path_kind",
+        "path",
+        "script",
+        "dispatch",
+        "enabled",
+    ]);
+    for r in rows {
+        table.row([
+            r.method,
+            r.host,
+            r.path_kind,
+            r.path,
+            r.script,
+            r.dispatch,
+            r.enabled.to_string(),
+        ]);
+    }
+    table.print(mode);
+    Ok(())
+}
+
 #[allow(clippy::too_many_arguments)]
 pub async fn create(
     script_id: &str,

crates/picloud-cli/src/main.rs

@@ -821,8 +821,14 @@ impl From<InstanceRoleArg> for picloud_shared::InstanceRole {
 
 #[derive(Subcommand)]
 enum RoutesCmd {
-    /// List routes bound to a script.
-    Ls { script_id: String },
+    /// List routes bound to a script, or a group's route TEMPLATES (`--group`).
+    Ls {
+        #[arg(conflicts_with = "group", required_unless_present = "group")]
+        script_id: Option<String>,
+        /// List the group's §11 tail route templates instead.
+        #[arg(long)]
+        group: Option<String>,
+    },
 
     /// Create a new route. Host defaults to `*` (any). Path-kind
     /// defaults to `exact`. Dispatch defaults to `sync`.
@@ -1608,8 +1614,12 @@ async fn main() -> ExitCode {
             Err(e) => Err(e),
         },
         Cmd::Routes {
-            cmd: RoutesCmd::Ls { script_id },
-        } => cmds::routes::ls(&script_id, mode).await,
+            cmd: RoutesCmd::Ls { script_id, group },
+        } => match (script_id, group) {
+            (_, Some(group)) => cmds::routes::ls_group(&group, mode).await,
+            (Some(script_id), None) => cmds::routes::ls(&script_id, mode).await,
+            (None, None) => Err(anyhow::anyhow!("provide a script id or --group")),
+        },
         Cmd::Routes {
             cmd:
                 RoutesCmd::Create {

crates/picloud-cli/src/manifest.rs

@@ -762,13 +762,22 @@ mod tests {
         assert_eq!(m.slug(), "acme");
         assert_eq!(m.scripts.len(), 1);
 
-        // A group cannot carry routes/triggers.
-        let err = Manifest::parse(
+        // §11 tail: a group MAY carry ROUTE templates (inherited by descendants).
+        let routed = Manifest::parse(
             "[group]\nslug = \"acme\"\nname = \"ACME\"\n\n\
              [[routes]]\nscript = \"shared\"\nhost_kind = \"any\"\npath_kind = \"exact\"\npath = \"/x\"\n",
         )
-        .expect_err("group with routes is rejected");
-        assert!(err.to_string().contains("routes"), "got: {err}");
+        .expect("group with a route template parses");
+        assert!(routed.is_group());
+        assert_eq!(routed.routes.len(), 1);
+
+        // ...but a STATEFUL trigger kind (cron/queue/email) on a group is rejected.
+        let err = Manifest::parse(
+            "[group]\nslug = \"acme\"\nname = \"ACME\"\n\n\
+             [[triggers.cron]]\nscript = \"shared\"\nschedule = \"0 0 * * * *\"\n",
+        )
+        .expect_err("group with a cron trigger is rejected");
+        assert!(err.to_string().contains("event kind"), "got: {err}");
 
         // Neither / both is rejected.
         Manifest::parse("[vars]\nx = 1\n").expect_err("no [app] or [group]");