docs: define deployment zone overlays

docs/FabricDiscoveryAndUpdate.md

@@ -91,17 +91,87 @@ Views can filter by repository, service, environment, machine, endpoint, tenant,
 workstream, deployment stack, or business capability. Views do not define fabric
 membership and should not mutate fabric boundaries.
 
+Zone views are a special kind of view. They group the subgraph by deployment
+environment, deployment scenario, routing authority, or access zone. They are
+useful for questions such as:
+
+- which services are currently visible in private dev, shared test, or
+  production;
+- which control surfaces appear in user-facing zones;
+- which production surfaces still have unrestricted developer access;
+- which routes exist in production but not in test;
+- which early-access interfaces lack an explicit policy authority.
+
 ### Environment
 
 An environment such as local, dev, staging, production, or lab is a deployment
 classification inside a fabric. It is not a fabric by itself.
 
+Railiance uses these baseline environment terms:
+
+| Environment | Meaning |
+|-------------|---------|
+| `dev` | Private developer-local execution. Useful for debugging and discovery, but not shared truth for other developers unless explicitly published. |
+| `test` | Shared central test stage for collaborators and friendly early-access users. |
+| `prod` | Production execution. Alpha-stage developer access may exist now, but production must be able to move toward restricted operator access and applicable security and data-privacy controls. |
+
 ### Deployment Scenario
 
 A deployment scenario is a realized or planned arrangement of services,
 machines, endpoints, automation, and configuration. It belongs inside a fabric
 or subfabric but does not define the financial boundary.
 
+Current Railiance scenario names:
+
+| Scenario | Environment | Meaning |
+|----------|-------------|---------|
+| `bernd-laptop` | `dev` | Private local workstation scenario. It may discover useful loopback services and ports, but it is not a shared developer environment. |
+| `coulombcore` | `test` | Central shared test-stage server for developers and friendly early-access users. |
+| `railiance01` | `prod` | Production host. It is still alpha-accessible to developers, but the intended direction is restricted production access. |
+
+### Routing Authority
+
+A routing authority is the deployment component that maps an external name,
+local URL, ingress host, or port to a backend service. Fabric discovers routing
+authority output; it does not allocate ports or author routes.
+
+Examples:
+
+- local loopback process launch configuration for developer tools;
+- Makefile or script defaults for local-only bootstrap surfaces;
+- Docker Compose published ports;
+- Kubernetes `Service`, `Ingress`, or controller-specific route manifests;
+- Traefik, nginx, Caddy, HAProxy, or other reverse-proxy configuration;
+- DNS records and TLS/certificate automation when they prove reachable names.
+
+### Access Zone
+
+An access zone is a visualization and discovery overlay that describes who a
+surface is intended to be reachable by in a deployment scenario. It is not a
+fabric boundary and does not define the policy itself.
+
+Useful initial access zones:
+
+| Access zone | Intended reach |
+|-------------|----------------|
+| `private-dev` | One developer's local machine. |
+| `collaborator-test` | Collaborating developers in the shared test stage. |
+| `early-access` | Friendly users participating in early access. |
+| `production-public` | Production user-facing surfaces. |
+| `production-admin` | Production administrative or control surfaces. |
+
+### Policy Authority
+
+A policy authority is the system expected to enforce access rules for a surface.
+Fabric may record which authority is in play, such as NetKingdom IAM, an ingress
+policy, network policy, or local-only loopback binding, but Fabric does not
+define or enforce those rules.
+
+These terms let the graph say: "this service belongs to the Railiance primary
+fabric, runs in the `coulombcore` test scenario, is routed by Traefik, and is
+intended for the `early-access` zone." That is a deployment and access overlay,
+not a change to fabric membership.
+
 ## Ownership Rule
 
 Every node in the Fabric graph must carry owner information.
@@ -277,7 +347,15 @@ For now, use:
 - king, lord, and tenant for financial responsibility actors;
 - fabric and subfabric for durable responsibility boundaries;
 - view for diagnostic graph slices;
-- environment for deployment classification.
+- environment for deployment classification;
+- deployment scenario for a concrete place where services run;
+- routing authority for the component that maps names or ports to services;
+- access zone for the visualization overlay that groups intended reachability;
+- policy authority for the external system expected to enforce access rules.
+
+Access zones may be security-relevant, but they are not Fabric security policy.
+They are discovered and visualized evidence that helps operators spot misplaced
+surfaces, missing policy authorities, or accidental exposure.
 
 ## State Hub Role
 

docs/financial-fabric-operator-guide.md

@@ -26,6 +26,28 @@ It defines:
 The baseline is not a security-zone model. Do not introduce realm, domain, or
 identity-zone language into the Fabric core when updating it.
 
+## Deployment Overlay Baseline
+
+Fabric membership is not the same as deployment environment. Use these current
+Railiance deployment overlays when interpreting discovery evidence:
+
+| Scenario | Environment | Access zone baseline | Notes |
+|----------|-------------|----------------------|-------|
+| `bernd-laptop` | `dev` | `private-dev` | Local machine used by one developer. Its loopback ports and local tools are useful evidence for debugging, but are not shared truth for other developers. |
+| `coulombcore` | `test` | `collaborator-test`, `early-access` | Central test-stage server for collaborating developers and friendly early-access users. |
+| `railiance01` | `prod` | `production-public`, `production-admin` | Production host. Developer access exists during alpha, but production should be able to move toward restricted operator access and applicable security and data-privacy controls. |
+
+The routing authority is the source that maps names or ports to services in a
+scenario. For local dev this may be a Makefile, script, process launcher, or
+loopback binding. For test and production this should usually come from
+Kubernetes `Service` and `Ingress`, Traefik/nginx/Caddy/HAProxy configuration,
+DNS, and TLS automation.
+
+Fabric should discover those routes and visualize the resulting zones. It
+should not allocate ports, author reverse-proxy config, or define the access
+policy. The policy authority is external evidence, such as NetKingdom IAM,
+ingress policy, network policy, or local-only loopback binding.
+
 ## Refresh Loop
 
 Run these checks from the `railiance-fabric` repo after changing declarations,

docs/graph-explorer-contract.md

@@ -89,6 +89,13 @@ Hosts should also include useful optional fields when available: `label`,
 `freshnessState`, `confidence`, `visualSize`, `ownership`, `unresolved`,
 `sourceReferences`, and `deepLinks`.
 
+Fabric hosts should also include deployment overlay fields when available:
+`deploymentEnvironment`, `deploymentScenario`, `routingAuthority`,
+`accessZone`, `policyAuthority`, `exposure`, and `host`. These fields describe
+where an element runs or is reachable in a concrete deployment scenario. They
+do not define fabric membership and must remain filter/grouping metadata unless
+the host explicitly promotes a separate graph relationship with evidence.
+
 Edges may include layout hints used by the client-side layout engine:
 `sameRepo`, `sourceRepo`, `targetRepo`, `layoutAffinity`,
 `layoutIdealLength`, and `layoutElasticity`. Fabric uses these hints to keep
@@ -132,6 +139,30 @@ The first Fabric manifest declares:
 | `binding` | Binding assertions between consumer dependencies and providers. |
 | `library` | Future library/SBOM inventory nodes. |
 
+## Zone Overlay Modes
+
+The graph explorer should support zone-oriented modes for Fabric payloads:
+
+| Mode | Purpose |
+|------|---------|
+| `fabric` | Group by financial responsibility: fabric, subfabric, owner. |
+| `environment` | Group by `dev`, `test`, `prod`, or other deployment environment. |
+| `deployment-scenario` | Group by concrete scenario such as `bernd-laptop`, `coulombcore`, or `railiance01`. |
+| `routing-authority` | Group by loopback launcher, Compose port mapping, ingress controller, reverse proxy, DNS, or equivalent route authority. |
+| `access-zone` | Group by intended reachability such as `private-dev`, `collaborator-test`, `early-access`, `production-public`, or `production-admin`. |
+
+Zone modes are diagnostic views. They answer "where does this run or who can
+reach it here?" without mutating the underlying Fabric responsibility boundary.
+
+Useful warnings for the graph explorer include:
+
+- control surfaces in user-facing access zones;
+- production nodes with unrestricted developer access;
+- early-access routes without a policy authority;
+- services present in production but missing from test;
+- local-only surfaces that appear in shared or production scenarios;
+- conflicting port or host claims within the same deployment scenario.
+
 ## Repo-Scoping Compatibility
 
 Repo-scoping can adapt without a rewrite because its current graph payload
@@ -167,3 +198,5 @@ Host repos should own:
 - authentication and authorization
 - domain-specific graph modes
 - deep links back to source systems
+- deployment overlay extraction from the route/proxy/deployment authority they
+  control