docs: README, runtime config, CI placeholder

README explains: - guildhall = ceremony orchestrator + governance UI - guildhall != ceremony engine (that's substrate) - five umbrella apps with responsibilities - local dev setup (mix deps.get + ecto.setup + phx.server) - runtime config env vars (DATABASE_URL, SECRET_KEY_BASE, PHX_HOST, POOL_SIZE, ECTO_IPV6) - relationship to substrate, bxnet-ops, guildhouse-specs - links to all relevant design docs .forgejo/workflows/ placeholder for CI (future WS2 work). Runtime config (config/runtime.exs) reads DATABASE_URL with ECTO_IPV6 socket option support. Commented placeholders for KUBECONFIG (substrate CRD watcher) and OIDC_* (Keycloak) are explicit about what comes in future sprints. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> Signed-off-by: Tyler J King <tking@guildhouse.dev>
2026-04-18 07:23:08 -04:00 · 2026-04-18 07:23:08 -04:00 · 0a6dd03e91
commit 0a6dd03e91
parent 48a7495ef5
2 changed files with 131 additions and 1 deletions
--- a/.forgejo/workflows/.gitkeep
+++ b/.forgejo/workflows/.gitkeep
@ -0,0 +1 @@
+# Placeholder for Forgejo CI workflows (WS2 follow-up)
--- a/README.md
+++ b/README.md
@ -1,4 +1,133 @@
 # Guildhall

-**TODO: Add description**
+**Ceremony orchestrator and governance UI — Elixir/Phoenix umbrella
+over substrate CRDs.**

+`guildhall` presents and coordinates; [`substrate`](../substrate) decides
+and enforces. The ceremony *engine* is a Rust Kubernetes operator
+with CRDs and etcd-backed state. `guildhall` is the *orchestrator*:
+it coordinates humans around those CRDs — notifying witnesses,
+collecting signatures via LiveView, tracking status, rendering
+dashboards.
+
+```
+┌────────────────────────────────────────────────────────┐
+│ SUBSTRATE (Rust, K8s operators) — decides + enforces    │
+│   CeremonyEngine (CRD), AccordEvaluator (CRD),          │
+│   CorpusReconciler (CRD), PostureEvaluator (CRD),       │
+│   Chronicle collector (agent)                           │
+└────────────────────┬───────────────────────────────────┘
+                     │ watches CRDs + emits Chronicle events
+                     ▼
+┌────────────────────────────────────────────────────────┐
+│ GUILDHALL (Elixir/Phoenix) — orchestrates + presents    │
+│   CeremonyOrchestrator (workflow coordinator)           │
+│   AccordComposer (UI + submission)                      │
+│   ArtifactBrowser (UI + lifecycle)                      │
+│   PostureDashboard (visualization)                      │
+│   ChronicleConsumer (projector + UI)                    │
+└────────────────────────────────────────────────────────┘
+```
+
+**Naming discipline:** `guildhall` components are *orchestrators*
+(workflow, coordination, presentation). The substrate components
+are *engines* and *reconcilers* (enforcement, state-machine
+advancement). Never call a `guildhall` component by a substrate
+name.
+
+---
+
+## Umbrella apps
+
+| App | Role |
+|-----|------|
+| `guildhall_web` | Phoenix LiveView UI — dashboards, ceremonies, artifacts, posture |
+| `guildhall_orchestrator` | Watches substrate CRDs (future), notifies witnesses, broadcasts ceremony status over PubSub |
+| `guildhall_ops_db` | Ecto schemas for the five Ops DB tables (per DESIGN-OPS-DB-CHAIN-OF-CUSTODY-0001) |
+| `guildhall_graph_bridge` | Microsoft Graph API reconciler — Intune deployment (stub) |
+| `guildhall_chronicle` | Chronicle event consumer + Ops DB projector (stub) |
+
+---
+
+## Local development
+
+### Prerequisites
+
+- Elixir 1.17.x + OTP 27 (via `mise` or `asdf`)
+- Postgres 14+ running on `localhost:5432` with a `postgres`
+  superuser (password `postgres` for dev)
+
+### First-time setup
+
+```bash
+mix deps.get
+mix ecto.create
+mix ecto.migrate
+mix run apps/guildhall_ops_db/priv/repo/seeds.exs
+```
+
+### Run the server
+
+```bash
+mix phx.server
+```
+
+Then visit:
+
+- <http://localhost:4000/> — governance dashboard
+- <http://localhost:4000/ceremonies> — open ceremonies
+- <http://localhost:4000/artifacts> — governed artifacts registry
+
+### Run tests
+
+```bash
+mix test
+```
+
+---
+
+## Configuration
+
+Development defaults are in `config/dev.exs` (Postgres at
+`localhost:5432` as `postgres`/`postgres`, database
+`guildhall_dev`). Production runtime configuration reads from
+environment variables in `config/runtime.exs`:
+
+| Env var | Purpose |
+|---------|---------|
+| `DATABASE_URL` | Postgres connection (required in prod) |
+| `SECRET_KEY_BASE` | Phoenix cookie/session signing (required in prod) |
+| `PHX_HOST` | Public hostname (default `guildhall.guildhouse.dev`) |
+| `PHX_SERVER` | Set to `true` to run the HTTP server under `mix release` |
+| `POOL_SIZE` | DB pool size (default 10) |
+| `ECTO_IPV6` | Set to `true` for IPv6 DB connections |
+
+Commented placeholders exist for future sprints: `KUBECONFIG`
+(substrate CRD watcher) and `OIDC_ISSUER` / `OIDC_CLIENT_ID` /
+`OIDC_CLIENT_SECRET` (Keycloak auth).
+
+---
+
+## Relationship to the rest of the stack
+
+`guildhall` is one of the PaaS components (ROADMAP WS1). It sits
+alongside:
+
+- `substrate` — the governance Rust crates + K8s operators
+- `bxnet-ops` — the `org-ops` CLI framework (reference fork: BXNet)
+- `guildhouse-mcp` — MCP server for LLM mediator context
+- `guildhouse-specs` — the FFC specifications
+
+See the design docs for the full picture:
+
+- [DESIGN-OPS-DB-CHAIN-OF-CUSTODY-0001](../guildhouse-specs/design/DESIGN-OPS-DB-CHAIN-OF-CUSTODY-0001.md) — Ops DB schema + self-hosted FFC threat model
+- [DESIGN-HFL-DB-ENFORCEMENT-0001](../guildhouse-specs/design/DESIGN-HFL-DB-ENFORCEMENT-0001.md) — BPF map ABI for DB governance
+- [DESIGN-ORG-OPS-FRAMEWORK-0001](../guildhouse-specs/design/DESIGN-ORG-OPS-FRAMEWORK-0001.md) — governed full-stack framework
+- [DESIGN-FORGE-WORKSPACE-0001](../guildhouse-specs/design/DESIGN-FORGE-WORKSPACE-0001.md) — governed workspace staging
+- [SPEC-CEREMONY-0001](../guildhouse-specs/family/ffc-app/SPEC-CEREMONY-0001.md) — ceremony protocol
+
+---
+
+## License
+
+Apache 2.0.
				`@ -0,0 +1 @@`
				`# Placeholder for Forgejo CI workflows (WS2 follow-up)`