feat: User-defined profiles — named presets for policy, quota, scaling, and reconciler tuning

Makefile

@@ -31,6 +31,7 @@ ork: generate-notes
 	cd $(ORKESTRA_DIR) && gofmt -w .
 	cd $(ORKESTRA_DIR) && go build -ldflags "$(ORK_LDFLAGS)" -o $(OUTPUT_DIR)/ork ./cmd/orkestra
 	@echo "✅ Orkestra built successfully"
+	@python3 scripts/fix-bare-fences.py documentation/
 
 orkcc:
 	@echo "Building Orkestra Control Center..."

cmd/cli/validate.go

@@ -521,6 +521,9 @@ func validateMotifFile(path string) error {
 		if summary := motifResourceSummary(m); summary != "" {
 			fmt.Printf("    %s\n", gray("resources: "+summary))
 		}
+		if summary := motifProfileSummary(m); summary != "" {
+			fmt.Printf("    %s\n", gray("profiles : "+summary))
+		}
 	}
 
 	fmt.Println()
@@ -529,6 +532,28 @@ func validateMotifFile(path string) error {
 	return nil
 }
 
+// motifProfileSummary returns a compact string listing non-empty profile classes
+// and their counts, e.g. "networkPolicies(2) resourceQuotas(1)".
+func motifProfileSummary(m *orktypes.Motif) string {
+	reg := m.Profiles
+	if reg.IsEmpty() {
+		return ""
+	}
+	var parts []string
+	add := func(kind string, n int) {
+		if n > 0 {
+			parts = append(parts, fmt.Sprintf("%s(%d)", kind, n))
+		}
+	}
+	add("networkPolicies", len(reg.NetworkPolicies))
+	add("resourceQuotas", len(reg.ResourceQuotas))
+	add("limitRanges", len(reg.LimitRanges))
+	add("hpa", len(reg.HPA))
+	add("pdb", len(reg.PDB))
+	add("rollingUpdate", len(reg.RollingUpdate))
+	return strings.Join(parts, " ")
+}
+
 // motifResourceSummary returns a compact string listing non-empty resource types
 // and their counts, e.g. "deployments(1) services(1) networkPolicies(2)".
 func motifResourceSummary(m *orktypes.Motif) string {

documentation/concepts/profiles/10-user-defined-profiles.md

@@ -0,0 +1,174 @@
+# User-Defined Profiles
+
+Built-in Orkestra profiles cover the common cases. User-defined profiles let your team define the cases specific to you — your network topology, your compliance requirements, your capacity tiers — and name them so that intent travels through every Katalog and Motif that imports them.
+
+---
+
+## Declaring profiles
+
+Profiles are declared at the root of a Katalog or Motif alongside `spec:` and `security:`:
+
+```yaml
+apiVersion: orkestra.orkspace.io/v1
+kind: Katalog
+metadata:
+  name: platform-operator
+
+profiles:
+  networkPolicies:
+    - name: allow-monitoring
+      description: Allow ingress from the platform monitoring namespace
+      ingress:
+        - from:
+            - namespaceSelector:
+                team: platform
+      policyTypes: [Ingress]
+
+  resourceQuotas:
+    - name: team-medium
+      description: Standard allocation for a medium-sized team namespace
+      hard:
+        pods: "30"
+        cpu: "6"
+        memory: "12Gi"
+        requests.cpu: "3"
+        requests.memory: "6Gi"
+
+spec:
+  crds:
+    namespace:
+      ...
+      operatorBox:
+        onCreate:
+          networkPolicies:
+            - name: "{{ .metadata.name }}-monitoring"
+              profile: allow-monitoring
+          resourceQuotas:
+            - name: "{{ .metadata.name }}-quota"
+              profile: team-medium
+```
+
+---
+
+## Supported profile classes
+
+| Class | YAML key | Expands into |
+|-------|----------|--------------|
+| NetworkPolicy | `profiles.networkPolicies` | ingress/egress rules, policyTypes |
+| ResourceQuota | `profiles.resourceQuotas` | hard limits map |
+| LimitRange | `profiles.limitRanges` | limit items |
+| HPA | `profiles.hpa` | minReplicas, maxReplicas, CPU target, behavior |
+| PDB | `profiles.pdb` | minAvailable or maxUnavailable |
+| Rolling Update | `profiles.rollingUpdate` | maxSurge, maxUnavailable |
+
+---
+
+## Template expressions in profile fields
+
+Profile field values support template expressions. They are resolved at reconcile time against the live CR:
+
+```yaml
+profiles:
+  resourceQuotas:
+    - name: cr-sized
+      hard:
+        pods: "{{ .spec.maxPods }}"
+        cpu: "{{ .spec.cpuLimit }}"
+        memory: "{{ .spec.memLimit }}"
+
+  hpa:
+    - name: cr-scaled
+      minReplicas: "{{ .spec.minReplicas | default \"2\" }}"
+      maxReplicas: "{{ .spec.maxReplicas }}"
+      targetCPUUtilizationPercentage: "70"
+```
+
+At `ork validate` time, fields containing `{{` are skipped — they cannot be validated statically. At reconcile time, the expression is expanded before the profile is applied.
+
+---
+
+## Validation
+
+`ork validate` enforces three rules on the `profiles:` block:
+
+1. **Non-empty name** — every profile entry must declare a `name`.
+2. **Unique within class** — two `networkPolicies` entries with the same name is an error. Two entries with the same name in different classes (`resourceQuotas` and `hpa`) is fine — class is the scope boundary.
+3. **Shadowing built-ins** — allowed but warned. If you declare a `networkPolicies` profile named `deny-all`, your version is used instead of Orkestra's built-in. A warning is printed at validate time so the shadowing is explicit.
+
+---
+
+## Resolution order
+
+When a resource declares `profile: some-name`, Orkestra resolves it in this order:
+
+1. User-defined profiles in the katalog `profiles:` block
+2. User-defined profiles merged from imported Motifs
+3. Built-in Orkestra profiles
+
+The first match wins. Built-ins are only consulted when the name is not found in any user registry.
+
+---
+
+## Profiles in Motifs
+
+A Motif can declare its own `profiles:` block. When a Katalog imports the Motif, its profiles are merged into the Katalog's registry:
+
+```yaml
+# tenant-isolation.motif.yaml
+apiVersion: orkestra.orkspace.io/v1
+kind: Motif
+metadata:
+  name: tenant-isolation
+  version: v0.2.0
+
+profiles:
+  networkPolicies:
+    - name: allow-monitoring
+      ingress:
+        - from:
+            - namespaceSelector:
+                team: platform
+      policyTypes: [Ingress]
+    - name: allow-internal
+      ingress:
+        - from:
+            - namespaceSelector:
+                scope: internal
+      policyTypes: [Ingress]
+
+resources:
+  networkPolicies:
+    - name: "{{ .metadata.name }}-deny-all"
+      profile: deny-all
+    - name: "{{ .metadata.name }}-monitoring"
+      profile: allow-monitoring
+```
+
+### Conflict detection
+
+If the same profile name appears in the same class in both the Katalog and an imported Motif — or in two imported Motifs — it is a **hard error** at load time:
+
+```text
+profile conflict: networkPolicies "allow-monitoring" defined in both motif "tenant-isolation" and the katalog
+```
+
+The same name in different classes is not a conflict — `resourceQuotas.medium` and `hpa.medium` are independent.
+
+---
+
+## ork validate output
+
+When a Motif declares profiles, `ork validate` shows them alongside resources:
+
+```text
+● tenant-isolation
+  Reusable network isolation motif
+  version  : v0.2.0
+  inputs   : 2
+  resources: networkPolicies(1)
+  profiles : networkPolicies(2)
+```
+
+---
+
+→ Back: [09 — NetworkPolicy Profile](09-networkpolicy-profile.md) | [Profiles index](index.md)

documentation/concepts/profiles/index.md

@@ -62,6 +62,46 @@ Static names are validated at load time. Template expressions are validated when
 
 ---
 
+## Built-ins versus user-defined profiles
+
+Orkestra ships with built-in profiles — `deny-all`, `small/medium/large/xlarge`, `safe`, `zero-downtime` — so the feature works immediately without any extra YAML. They cover common Kubernetes patterns.
+
+But the feature is designed for the profiles you write yourself.
+
+A team writing `profile: org-medium` is expressing an organizational contract: this namespace gets the capacity we agreed on for medium-sized teams. The numbers follow from that decision. Change the `org-medium` definition once and it propagates to every Katalog and Motif that references it — no grep, no PR chain, no drift.
+
+That is what built-ins cannot do. `medium` is Orkestra's guess at what medium means. `org-medium` is your team's actual answer.
+
+User-defined profiles are declared in a `profiles:` block at the root of any Katalog or Motif:
+
+```yaml
+profiles:
+  resourceQuotas:
+    - name: org-medium
+      description: Standard allocation for a medium-sized team namespace
+      hard:
+        pods: "25"
+        cpu: "4"
+        memory: "8Gi"
+
+  networkPolicies:
+    - name: org-deny-all
+      description: Block all traffic — start here and add policies for what you need
+      policyTypes: [Ingress, Egress]
+
+  rollingUpdate:
+    - name: org-safe
+      description: Never reduces capacity during a rollout
+      maxSurge: "1"
+      maxUnavailable: "0"
+```
+
+They resolve before built-ins. A profile named `deny-all` in your `profiles:` block shadows the built-in. A conflict between two imported Motifs declaring the same profile name in the same class is a hard error at load time.
+
+See [User-defined profiles](./10-user-defined-profiles.md) for the full reference.
+
+---
+
 ## Profile families
 
 | Family | What it controls | Applied to |
@@ -75,6 +115,7 @@ Static names are validated at load time. Template expressions are validated when
 | [Rolling Update](./07-rolling-update-profile.md) | Deployment/StatefulSet/ReplicaSet rollout strategy | `deployments[*].rollingUpdate`, `statefulSets[*].rollingUpdate`, `replicaSets[*].rollingUpdate` |
 | [ResourceQuota](./08-resourcequota-profile.md) | Namespace resource limits (pods, CPU, memory) | `resourceQuotas[*]` |
 | [NetworkPolicy](./09-networkpolicy-profile.md) | Traffic allow/deny rules for pods | `networkPolicies[*]` |
+| [User-defined](./10-user-defined-profiles.md) | Custom named profiles declared in your Katalog or Motif | All profile-supporting fields |
 
 ---
 
@@ -84,3 +125,4 @@ Static names are validated at load time. Template expressions are validated when
 - **Fail-fast** — an unknown profile name is a Katalog load error, not a runtime error.
 - **No mixing** — a profile and explicit fields of the same type cannot coexist on the same resource.
 - **Template-safe** — profile names can be template expressions. Static names are validated immediately; template expressions are validated at reconcile time.
+- **User-defined** — teams can declare custom named profiles in a Katalog or Motif `profiles:` block. They resolve before built-ins. See [User-defined profiles](./10-user-defined-profiles.md).

documentation/reference/schema/02-katalog/index.md

@@ -40,6 +40,14 @@ spec:
       imports:                 # Motif imports
         ...
 
+profiles:                      # optional — user-defined named profiles
+  networkPolicies:
+    - name: allow-monitoring
+      ...
+  resourceQuotas:
+    - name: team-medium
+      ...
+
 security:                      # optional
   ...
 
@@ -80,6 +88,8 @@ This scaffolds the simplest Katalog — a single CRD that creates a Deployment a
 | [10-katalog-security.md](10-katalog-security.md) | `security` block |
 | [11-katalog-notification.md](11-katalog-notification.md) | `notification` block |
 | [12-katalog-providers.md](12-katalog-providers.md) | `providers` block |
+| [16-resource-types.md](16-resource-types.md) | Supported Kubernetes resource types |
+| [Profiles concept](../../../concepts/profiles/10-user-defined-profiles.md) | `profiles:` — user-defined named profiles |
 | [15-enrich.md](15-enrich.md) | `enrich` — post-reconcile enrichment |
 | [16-resource-types.md](16-resource-types.md) | Supported resource types and placeholder fields |
 

examples/beginner/03-secret-copy/README.md

@@ -40,7 +40,7 @@ ork simulate
 
 Because the Secret copy requires reading the source Secret from a live cluster, Orkestra detects this automatically and skips it during simulation:
 
-```
+```text
 note: secrets/{{ .spec.secretName }}: cross-namespace copy skipped in simulate — requires a live cluster
 
   Cycle 1:

examples/use-cases/namespace-provisioner/03-user-defined-profiles/cr.yaml

@@ -0,0 +1,10 @@
+apiVersion: provisioner.orkestra.io/v1
+kind: NamespaceClaim
+metadata:
+  name: team-gamma-claim
+spec:
+  targetNamespace: team-gamma
+  team: gamma
+  owner: gamma-operator
+  ownerNamespace: default
+  tier: medium