# 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.