From 061e2206ea9058ebc60a9bc6f5fe747ac35558d02dbc06c3d510db8d641e0dbd Mon Sep 17 00:00:00 2001
From: Tyler J King <tking@guildhouse.dev>
Date: Mon, 4 May 2026 11:41:30 -0400
Subject: [PATCH] docs: add CLAUDE.md

Documents the 2 crates (gsh binary + libgsh library), the GSH_*
env-var contract that bascule sets and forge-fuse reads (Phase 3
shell-IS-session), the cross-workspace dependency on
forge-core::CorpusCapabilityCeiling for the runtime three-way
intersection, and the local dev-environment/ playbook for the
WSL2 + Bascule + Hetzner Keycloak + Entra federation flow.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Signed-off-by: Tyler J King <tking@guildhouse.dev>
---
 CLAUDE.md | 51 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 51 insertions(+)
 create mode 100644 CLAUDE.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..14ecf4a
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,51 @@
+# CLAUDE.md — gsh
+
+The governed shell. Operator-facing CLI that bascule launches after
+OIDC → DID derivation; the binary that consumes `GSH_*` env vars,
+loads the AC, validates the corpus, and runs governed commands.
+Substrate-level (carries the Guildhouse brand intentionally per
+`TODO.md` Layout Principle).
+
+## Crates
+
+- **gsh** — The governed shell binary itself (`GCAP-SPEC-SHELLBOUND-
+  SDK-0001`). Consumes `GSH_DID`, `GSH_ACCORD_HASH`, `GSH_SHELL_CLASS`,
+  `GSH_POSTURE_LEVEL`, `GSH_CAPABILITY_SET` from bascule + propagates
+  to subprocesses via `org-ops-core::context::GshContext` headers.
+- **libgsh** — Library: AC validation, capability-request building,
+  corpus gate. The shell binary's reusable surface.
+
+## Cross-workspace dependencies
+
+**Consumes:** `guildhouse-did` (Did parsing/derivation),
+`bascule-workspace/bascule-core` (`AuthorizationContext` shape),
+`org-ops-core` (env-var contract for child-process governance
+threading), `forge-core::shell_context` (re-exported
+`CorpusCapabilityCeiling` for runtime intersection).
+
+**Consumed by:** the operator's interactive session — invoked by
+bascule-shell after OIDC auth, by `dev-environment/bascule-local.toml`
+locally on WSL2.
+
+## Build / Test
+
+```bash
+CARGO_TARGET_DIR=target-tking cargo build --workspace
+CARGO_TARGET_DIR=target-tking cargo test  --workspace
+```
+
+## Architectural notes
+
+- **`GSH_*` env contract** is the load-bearing interop with bascule
+  (which sets them) and forge-fuse (which reads them via
+  `forge-fuse::ShellContext::from_env`). The contract:
+  `GSH_DID`, `GSH_ACCORD_HASH`, `GSH_SHELL_CLASS=Application|System`,
+  `GSH_POSTURE_LEVEL` (1..=5 DEFCON), `GSH_CAPABILITY_SET` (hex
+  bitmask `0x{:08x}`).
+- **Phase 3 forge-fuse (shell-IS-session)** consumes these env vars
+  to compute the per-mount effective capability via
+  `manifest_cap ∩ shell_cap ∩ corpus_cap`.
+- **Local dev environment** at `dev-environment/` shows the WSL2 +
+  Bascule + gsh + Hetzner Keycloak + Entra federation flow end-to-end.
+- The brand-bound `gsh` name (vs a `substrate-shell`) is preserved
+  intentionally — revisit when the substrate brand solidifies.