feat(cli): pic projects ls + §7 M3/track-complete docs

§7 M3 (part 3) — the ownership track becomes inspectable, completing M1–M3.

- server: GET /api/v1/admin/projects (projects_api) lists every project + its
  owned-group count (projects repo list_with_counts, one GROUP BY); behind the
  /admin middleware, like the groups list.
- CLI: pic projects ls (cmds/projects.rs + client projects_list); the
  apply_ownership plan-preview journey now also asserts projects ls (plat owns
  exactly 1 group; teamb listed).
- docs: design §7 + CLAUDE.md record M3 shipped and the whole §7 multi-repo
  ownership track (M1 claim · M2 attach ceiling · M3 preview + projects ls)
  COMPLETE; deferred = structural-divergence + declarative tree shape + per-env
  approval gating.

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

crates/manager-core/src/lib.rs

@@ -80,6 +80,7 @@ pub mod outbox_event_emitter;
 pub mod outbox_repo;
 pub mod principal_resolver;
 pub mod project_repo;
+pub mod projects_api;
 pub mod pubsub_repo;
 pub mod pubsub_service;
 pub mod queue_repo;
@@ -225,6 +226,7 @@ pub use outbox_repo::{
 };
 pub use principal_resolver::{AdminPrincipalResolver, PrincipalResolver, PrincipalResolverError};
 pub use project_repo::{PostgresProjectRepository, ProjectRepository, ProjectRepositoryError};
+pub use projects_api::{projects_router, ProjectsApiError, ProjectsState};
 pub use pubsub_repo::{PostgresPubsubRepo, PublishCtx, PubsubRepo, PubsubRepoError};
 pub use pubsub_service::{PubsubServiceImpl, SubscriberTokenConfig};
 pub use realtime_authority::RealtimeAuthorityImpl;

crates/manager-core/src/project_repo.rs

@@ -21,6 +21,9 @@ pub enum ProjectRepositoryError {
 pub trait ProjectRepository: Send + Sync {
     /// Every project on the instance, ordered by slug.
     async fn list(&self) -> Result<Vec<Project>, ProjectRepositoryError>;
+    /// Every project paired with how many group nodes it owns — backs
+    /// `pic projects ls`. One GROUP BY instead of N per-project counts.
+    async fn list_with_counts(&self) -> Result<Vec<(Project, i64)>, ProjectRepositoryError>;
     async fn get_by_id(&self, id: ProjectId) -> Result<Option<Project>, ProjectRepositoryError>;
     async fn get_by_slug(&self, slug: &str) -> Result<Option<Project>, ProjectRepositoryError>;
 }
@@ -40,6 +43,21 @@ const PROJECT_COLS: &str = "id, slug, name, created_by, created_at";
 
 #[async_trait]
 impl ProjectRepository for PostgresProjectRepository {
+    async fn list_with_counts(&self) -> Result<Vec<(Project, i64)>, ProjectRepositoryError> {
+        let rows = sqlx::query_as::<_, ProjectCountRow>(
+            "SELECT p.id, p.slug, p.name, p.created_by, p.created_at, \
+                    COUNT(g.id) AS owned_groups \
+             FROM projects p LEFT JOIN groups g ON g.owner_project = p.id \
+             GROUP BY p.id ORDER BY p.slug",
+        )
+        .fetch_all(&self.pool)
+        .await?;
+        Ok(rows
+            .into_iter()
+            .map(|r| (r.project.into(), r.owned_groups))
+            .collect())
+    }
+
     async fn list(&self) -> Result<Vec<Project>, ProjectRepositoryError> {
         let rows = sqlx::query_as::<_, ProjectRow>(&format!(
             "SELECT {PROJECT_COLS} FROM projects ORDER BY slug"
@@ -79,6 +97,14 @@ struct ProjectRow {
     created_at: chrono::DateTime<chrono::Utc>,
 }
 
+/// `list_with_counts` row: a project flattened with its owned-group count.
+#[derive(sqlx::FromRow)]
+struct ProjectCountRow {
+    #[sqlx(flatten)]
+    project: ProjectRow,
+    owned_groups: i64,
+}
+
 impl From<ProjectRow> for Project {
     fn from(r: ProjectRow) -> Self {
         Self {

crates/manager-core/src/projects_api.rs

@@ -0,0 +1,81 @@
+//! §7 M3 read-only projects surface: `GET /api/v1/admin/projects` — every
+//! project (repo-root) with the count of group nodes it owns. Backs
+//! `pic projects ls`. Behind the `/admin` middleware, so any authenticated
+//! admin can list them (a project reveals only org structure, like the groups
+//! list); ownership WRITES stay in the apply path.
+
+use std::sync::Arc;
+
+use axum::extract::State;
+use axum::http::StatusCode;
+use axum::response::{IntoResponse, Json, Response};
+use axum::routing::get;
+use axum::{Extension, Router};
+use chrono::{DateTime, Utc};
+use picloud_shared::Principal;
+use serde::Serialize;
+use serde_json::json;
+
+use crate::project_repo::{ProjectRepository, ProjectRepositoryError};
+
+#[derive(Clone)]
+pub struct ProjectsState {
+    pub projects: Arc<dyn ProjectRepository>,
+}
+
+/// Mounted under `/api/v1/admin`.
+pub fn projects_router(state: ProjectsState) -> Router {
+    Router::new()
+        .route("/projects", get(list_projects))
+        .with_state(state)
+}
+
+#[derive(Serialize)]
+struct ProjectListItem {
+    slug: String,
+    name: String,
+    owned_groups: i64,
+    created_at: DateTime<Utc>,
+}
+
+async fn list_projects(
+    State(s): State<ProjectsState>,
+    Extension(_principal): Extension<Principal>,
+) -> Result<Json<Vec<ProjectListItem>>, ProjectsApiError> {
+    let items = s
+        .projects
+        .list_with_counts()
+        .await?
+        .into_iter()
+        .map(|(p, owned_groups)| ProjectListItem {
+            slug: p.slug,
+            name: p.name,
+            owned_groups,
+            created_at: p.created_at,
+        })
+        .collect();
+    Ok(Json(items))
+}
+
+#[derive(Debug, thiserror::Error)]
+pub enum ProjectsApiError {
+    #[error("backend: {0}")]
+    Backend(String),
+}
+
+impl From<ProjectRepositoryError> for ProjectsApiError {
+    fn from(e: ProjectRepositoryError) -> Self {
+        Self::Backend(e.to_string())
+    }
+}
+
+impl IntoResponse for ProjectsApiError {
+    fn into_response(self) -> Response {
+        tracing::error!(error = %self, "projects api error");
+        (
+            StatusCode::INTERNAL_SERVER_ERROR,
+            Json(json!({ "error": "internal error" })),
+        )
+            .into_response()
+    }
+}