refactor(helix-org): org redesign — multi-tenant + streams + chart UX

.gitignore

@@ -137,4 +137,12 @@ api/settings-sync-daemon
 /scanout-stream-test
 core.*
 nohup.out
-# CI validation Mon Mar 30 17:38:01 BST 2026
+
+# Browser screenshots (Playwright runs, ad-hoc debug captures). The
+# tracked PNGs under design/cloud-smoke-screenshots/ and for-mac/ are
+# already in git; *.png only excludes new untracked ones.
+*.png
+
+# Playwright MCP trace dir (per-session screenshots, console logs,
+# accessibility snapshots). Local only — never check in.
+.playwright-mcp/

CLAUDE.md

@@ -214,6 +214,16 @@ These rules keep our list pages visually consistent. When in doubt, mirror `Sand
 - **RBAC**: `authorizeUserToResource()` — unified AccessGrants
 - **Enterprise**: Support internal DNS, proxies, air-gapped, private CAs
 
+## helix-org design philosophy
+
+Anything under `api/pkg/org/` is the org-graph runtime (Workers, Positions, Roles, Streams, Grants). Behaviour lives in the prompt/profile, not in Go code. The code is scaffolding.
+
+- **Prefer data and text over code.** If a feature can be expressed as a Role/Position prompt edit, a scope value, or a tool description, do that before adding Go logic.
+- **Keep the MCP surface small.** MCP tools are reserved for org-graph primitives (reads + mutations of Workers, Positions, Roles, Streams, Grants). Anything else a Worker needs goes through shell tools provisioned in their environment (`bash`, `curl`, `git`, `gh`, `python`). Don't add MCP wrappers like `publish_to_blog` or `fetch_url` — describe the shell usage in the Role text instead.
+- **No workflow in code.** Tools do exactly one thing. Code does not orchestrate multi-step sequences on behalf of an agent — it does not subscribe Workers, grant tools implicitly, auto-create related records. Orchestration lives in the prompt. `DefaultTools` / `DefaultStreams` on a Role are reference data the hiring manager's prompt reads, not triggers the code acts on. When reviewing a tool, ask: "is the code making a decision the agent should be making?" If yes, remove it.
+- **Social enforcement first.** A Worker reads scope from its prompt and complies. Reach for hard enforcement only when the cost of a violation is high.
+- **Keep the core generic.** Tool definitions and scope shapes live with the tool, not in the registry, server, or domain layer. New tools must be addable without editing the core.
+
 ## Dev Environment (Helix-in-Helix)
 
 **`helix-4` is a symlink to `helix`** — they are the same directory. Always use `/home/retro/work/helix/`.

api/pkg/config/config.go

@@ -78,9 +78,9 @@ type ServerConfig struct {
 	// HelixOrgEnabled is the deployment-wide kill switch for the
 	// embedded helix-org alpha. When false (the default), none of
 	// the helix-org init runs and none of its HTTP surfaces
-	// (/api/v1/org/, /ui/, /api/v1/mcp/helix-org/) are mounted —
-	// the per-user alpha feature flag in the DB has no effect.
-	// Set HELIX_ORG_ENABLED=true to opt in.
+	// (/api/v1/orgs/{org}/, /api/v1/mcp/helix-org/) are mounted —
+	// the per-user alpha feature flag in the DB has no effect. Set
+	// HELIX_ORG_ENABLED=true to opt in.
 	HelixOrgEnabled bool `envconfig:"HELIX_ORG_ENABLED" default:"false"`
 }
 

api/pkg/github/client.go

@@ -2,6 +2,8 @@ package github
 
 import (
 	"context"
+	"fmt"
+	"slices"
 
 	"github.com/google/go-github/v61/github"
 	"golang.org/x/oauth2"
@@ -49,32 +51,34 @@ func NewGithubClient(options ClientOptions) (*Client, error) {
 	}, nil
 }
 
+const loadReposMaxPages = 10
+
+// LoadRepos returns full_name for every repo the token can see,
+// sorted by most-recently-pushed first. Caps at loadReposMaxPages so
+// heavy accounts don't take minutes.
 func (c *Client) LoadRepos() ([]string, error) {
-	repos := []*github.Repository{}
-	opts := github.ListOptions{
-		PerPage: 100,
-		Page:    0,
-	}
-	for {
-		result, meta, err := c.client.Repositories.ListByUser(c.ctx, "", &github.RepositoryListByUserOptions{
+	var repos []*github.Repository
+	opts := github.ListOptions{PerPage: 100, Page: 1}
+	for i := 0; i < loadReposMaxPages; i++ {
+		result, meta, err := c.client.Repositories.ListByAuthenticatedUser(c.ctx, &github.RepositoryListByAuthenticatedUserOptions{
+			Sort:        "pushed",
+			Direction:   "desc",
 			ListOptions: opts,
 		})
 		if err != nil {
 			return nil, err
 		}
-		for _, repo := range result {
-			if repo != nil {
-				repos = append(repos, repo)
-			}
-		}
-		opts.Page = opts.Page + 1
-		if opts.Page > meta.LastPage {
+		repos = append(repos, result...)
+		if meta == nil || meta.NextPage == 0 {
 			break
 		}
+		opts.Page = meta.NextPage
 	}
-	results := []string{}
+	results := make([]string, 0, len(repos))
 	for _, repo := range repos {
-		results = append(results, *repo.FullName)
+		if repo != nil && repo.FullName != nil {
+			results = append(results, *repo.FullName)
+		}
 	}
 	return results, nil
 }
@@ -105,32 +109,94 @@ func (c *Client) AddWebhookToRepo(
 	events []string,
 	secret string,
 ) error {
+	_, err := c.UpsertWebhook(owner, repo, name, url, events, secret)
+	return err
+}
+
+type WebhookSummary struct {
+	ID     int64
+	Events []string
+}
+
+// UpsertWebhook creates a webhook on the repo if none points at `url`,
+// or PATCHes the existing one to bring content_type / events / active
+// in line. Events of `["*"]` is GitHub's wildcard.
+func (c *Client) UpsertWebhook(
+	owner string,
+	repo string,
+	name string,
+	url string,
+	events []string,
+	secret string,
+) (WebhookSummary, error) {
 	active := true
-	json := "application/json"
+	jsonCT := "application/json"
 
 	hooks, _, err := c.client.Repositories.ListHooks(c.ctx, owner, repo, nil)
 	if err != nil {
-		return err
+		return WebhookSummary{}, err
 	}
-
 	for _, hook := range hooks {
-		if hook.Config.URL != nil && *hook.Config.URL == url {
-			// Hook already exists, no need to add it again
-			return nil
+		if hook.Config == nil || hook.Config.URL == nil || *hook.Config.URL != url {
+			continue
+		}
+		needsUpdate := hook.Config.ContentType == nil || *hook.Config.ContentType != jsonCT ||
+			!sameEvents(hook.Events, events) ||
+			hook.Active == nil || !*hook.Active
+		if !needsUpdate || hook.ID == nil {
+			return summarizeHook(hook), nil
 		}
+		patched, _, err := c.client.Repositories.EditHook(context.Background(), owner, repo, *hook.ID, &github.Hook{
+			Active: &active,
+			Events: events,
+			Config: &github.HookConfig{
+				ContentType: &jsonCT,
+				URL:         &url,
+				Secret:      &secret,
+			},
+		})
+		if err != nil {
+			return WebhookSummary{}, fmt.Errorf("update github webhook: %w", err)
+		}
+		return summarizeHook(patched), nil
 	}
-
-	// Add the new hook
-	_, _, err = c.client.Repositories.CreateHook(context.Background(), owner, repo, &github.Hook{
+	created, _, err := c.client.Repositories.CreateHook(context.Background(), owner, repo, &github.Hook{
 		Active: &active,
 		Name:   &name,
 		URL:    &url,
 		Events: events,
 		Config: &github.HookConfig{
-			ContentType: &json,
+			ContentType: &jsonCT,
 			URL:         &url,
 			Secret:      &secret,
 		},
 	})
-	return err
+	if err != nil {
+		return WebhookSummary{}, err
+	}
+	return summarizeHook(created), nil
+}
+
+// WebhookSettingsURL returns the operator-facing edit page for a hook.
+func WebhookSettingsURL(owner, repo string, hookID int64) string {
+	return fmt.Sprintf("https://github.com/%s/%s/settings/hooks/%d", owner, repo, hookID)
+}
+
+func sameEvents(a, b []string) bool {
+	ca := slices.Clone(a)
+	cb := slices.Clone(b)
+	slices.Sort(ca)
+	slices.Sort(cb)
+	return slices.Equal(ca, cb)
+}
+
+func summarizeHook(h *github.Hook) WebhookSummary {
+	if h == nil {
+		return WebhookSummary{}
+	}
+	out := WebhookSummary{Events: h.Events}
+	if h.ID != nil {
+		out.ID = *h.ID
+	}
+	return out
 }