docs: align public face with HITL and provider reality (#44)

SafetyMP · Sage Hart · web-flow · commit d6812b2966a3 · 2026-07-26T19:49:19.000-04:00
* docs: align public face with HITL and provider reality

Correct overstated live-LLM, scenario, shared-mode, and G1–G6 claims;
add docs indexes and package repository metadata for the GitHub storefront.

* docs: clarify shared-mode console Bearer after r3 rebase

---------

Co-authored-by: Sage Hart &lt;sagehart@MacBookAir.attlocal.net&gt;
diff --git a/.env.example b/.env.example
@@ -16,11 +16,12 @@
 # PORT=3000
 
 # ── Model providers ──────────────────────────────────────────────────
-# Default is SimulationProvider (health.mode=simulation).
-# Live HttpLLMProvider only when BOTH are set:
+# Default is SimulationProvider (GET /api/health → mode=simulation).
+# Live *health reporting* when BOTH are set (agents still use SimulationProvider):
 #   CORPOS_ALLOW_LIVE=1
 #   OPENROUTER_API_KEY=...
-# OPENROUTER_API_KEY alone does NOT switch agents to live reasoning.
+# Optional override: CORPOS_PROVIDER=live|simulation
+# OPENROUTER_API_KEY alone does NOT switch health to live.
 # CORPOS_ALLOW_LIVE=0
 # OPENROUTER_API_KEY=
-# OPENROUTER_MODEL=openai/gpt-4o-mini
+# CORPOS_PROVIDER=
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
@@ -16,10 +16,12 @@
 ## Checklist
 
 - [ ] `./scripts/harness/verify.sh` is green locally.
+- [ ] `./scripts/harness/adversarial.sh` is green locally (or N/A for docs-only).
 - [ ] New behavior is covered by a test where applicable.
 - [ ] No Express or `better-sqlite3` introduced.
 - [ ] No secrets, `*.db`, `.env`, or `dist/` staged.
 - [ ] Reference-architecture posture preserved (README / SECURITY scope language not weakened).
+- [ ] Company-day / demo paths keep `autoApproveException` default-off unless a test/CI opt-in is intentional.
 - [ ] If this introduces or reverses a decision, an ADR is added/updated in `docs/adr/`.
 - [ ] If the ops console UI changed materially, README screenshots were regenerated (`npm run screenshots`).
 
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
@@ -54,12 +54,13 @@ representative at an online or offline event.
 ## Enforcement
 
 Instances of abusive, harassing, or otherwise unacceptable behavior may be
-reported to the repository maintainers via [GitHub Security Advisories on the
-CorpOS repository](https://github.com/SafetyMP/CorpOS/security/advisories/new)
-(for security-sensitive reports) or by contacting the SafetyMP maintainers
-through the organization profile. All complaints will be reviewed and
-investigated promptly and fairly. All community leaders are obligated to respect
-the privacy and security of the reporter of any incident.
+reported privately to the [SafetyMP maintainers](https://github.com/SafetyMP)
+(open a private contact via the GitHub profile, or email the account owner if
+listed). Do **not** use GitHub Security Advisories for conduct reports —
+advisories are reserved for vulnerabilities; see [SECURITY.md](SECURITY.md).
+All complaints will be reviewed and investigated promptly and fairly. All
+community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
 
 ## Enforcement Guidelines
 
diff --git a/CONTEXT.md b/CONTEXT.md
@@ -8,6 +8,13 @@ Workspaces: `packages/core`, `packages/mcp-knowledge`, `apps/api`, `apps/console
 Commands: `npm run dev`, `npm test`, `npm run scenario`, `npm run audit:verify`,
 `./scripts/harness/verify.sh`, `./scripts/harness/adversarial.sh`.
 
+- `npm run scenario` uses HITL default-off (`autoApproveException` unset) and exits
+  non-zero when the exception path is not auto-settled. Tests pass
+  `autoApproveException: true` for a green headless settle.
+- Live LLM requires `CORPOS_ALLOW_LIVE=1` and `OPENROUTER_API_KEY` (company-day uses
+  `HttpLLMProvider` when live; `/api/health.mode` reports `live` only then).
+- Shared mode (`CORPOS_MODE=shared` + `DASHBOARD_API_TOKEN`) gates approve/kill on
+  the API via Bearer; console sends `VITE_DASHBOARD_API_TOKEN` when configured.
+
 Site id: `corpos`. Program: `corpos-autonomous-company-r3`.
-Live LLM requires `CORPOS_ALLOW_LIVE=1` and `OPENROUTER_API_KEY` (company-day uses HttpLLMProvider when live).
 G1–G6 firm governance coded; TTL scheduler; console Bearer; orchestrator-driven day; live SSE.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -29,22 +29,26 @@ Please also follow the [Code of Conduct](CODE_OF_CONDUCT.md).
 ```bash
 npm ci --include=dev
 npm run build
-./scripts/harness/verify.sh   # build · typecheck · test · lint · format · stack guards
+./scripts/harness/verify.sh      # build · typecheck · test · lint · format · stack guards
+./scripts/harness/adversarial.sh # authorized local adversarial probes
 # Force a clean reinstall (CI does this): CORPOS_VERIFY_CLEAN=1 ./scripts/harness/verify.sh
 ```
 
 A contribution is not finished until `./scripts/harness/verify.sh` is green
-locally. CI runs the same gate on every pull request.
+locally. CI runs **verify and adversarial** on every pull request to `main`.
 
 Useful commands:
 
 ```bash
 npm run dev            # ops console on $PORT or 3000
 npm test
-npm run scenario
+npm run scenario       # HITL default-off; exits non-zero unless exception is auto-settled
 npm run audit:verify
 ```
 
+Headless company-day settles that must exit 0 need `autoApproveException: true`
+(used in tests). Product demos and the ops console keep it `false`.
+
 ## Architecture rules (must respect)
 
 - Workspaces: firm logic in [`packages/core`](packages/core), MCP knowledge in
@@ -59,8 +63,8 @@ npm run audit:verify
 ## Decisions
 
 Non-trivial architectural decisions are recorded as ADRs in
-[`docs/adr/`](docs/adr/). If your change introduces or reverses a decision, add
-or update an ADR.
+[`docs/adr/README.md`](docs/adr/README.md). If your change introduces or reverses
+a decision, add or update an ADR.
 
 ## Screenshots
 
@@ -87,6 +91,7 @@ npm run screenshots              # see docs/assets/README.md
 | **CodeQL**            | [`.github/workflows/codeql.yml`](.github/workflows/codeql.yml)       |
 | **Dependabot**        | [`.github/dependabot.yml`](.github/dependabot.yml)                   |
 | **Local verify**      | `./scripts/harness/verify.sh`                                        |
+| **Local adversarial** | `./scripts/harness/adversarial.sh`                                   |
 
 ## License
 
diff --git a/README.md b/README.md
@@ -4,19 +4,19 @@
 
 [![CI](https://github.com/SafetyMP/CorpOS/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/SafetyMP/CorpOS/actions/workflows/ci.yml)
 [![CodeQL](https://github.com/SafetyMP/CorpOS/actions/workflows/codeql.yml/badge.svg?branch=main)](https://github.com/SafetyMP/CorpOS/actions/workflows/codeql.yml)
-[![OpenSSF Scorecard](https://github.com/SafetyMP/CorpOS/actions/workflows/scorecard.yml/badge.svg?branch=main)](https://scorecard.dev/viewer/?uri=github.com/SafetyMP/CorpOS)
+[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/SafetyMP/CorpOS/badge)](https://scorecard.dev/viewer/?uri=github.com/SafetyMP/CorpOS)
 [![License: Apache-2.0](https://img.shields.io/github/license/SafetyMP/CorpOS)](LICENSE)
 [![Node](https://img.shields.io/badge/node-%E2%89%A522-339933?logo=node.js&logoColor=white)](#quick-start)
 
-CorpOS shows how a firm operates when department agents do most work and **humans govern by exception** (Approve / Reject / Kill in the ops console). Autonomy is earned from evidence, not granted in prompts. Interop protocols (MCP) are transport; **community governance (G1–G6)** lives in the firm.
+CorpOS shows how a firm operates when department agents do most work and **humans govern by exception** (Approve / Reject / Kill in the ops console). Autonomy is earned from evidence, not granted in prompts. Interop protocols (MCP) are transport; firm-side governance includes **G1 membership** and **G4 dissent** today, with a broader G1–G6 crosswalk in the docs.
 
 > **Scope:** Reference architecture and runnable demo — **not** a production-hardened SaaS. See [SECURITY.md](SECURITY.md).
 
 Default mode is **simulation** (`SimulationProvider`) for deterministic CI. Live LLM (`HttpLLMProvider`) drives company-day/orchestrator only when `CORPOS_ALLOW_LIVE=1` and `OPENROUTER_API_KEY` are set — `/api/health.mode` never lies. G1–G6 firm governance, orchestrator-driven day, TTL scheduler, console Bearer (shared mode), and live `/api/events` SSE are implemented.
 
-Read the thesis: [`docs/future-of-the-firm.md`](docs/future-of-the-firm.md). Governance crosswalk: [`docs/governance-crosswalk.md`](docs/governance-crosswalk.md). AIBOM: [`docs/aibom.json`](docs/aibom.json).
+Read the thesis: [`docs/future-of-the-firm.md`](docs/future-of-the-firm.md). Governance crosswalk: [`docs/governance-crosswalk.md`](docs/governance-crosswalk.md). AIBOM: [`docs/aibom.json`](docs/aibom.json). Docs index: [`docs/README.md`](docs/README.md).
 
-**Jump to:** [Demo](#demo) · [Quick start](#quick-start) · [Architecture](#architecture) · [Contributing](CONTRIBUTING.md) · [Security](SECURITY.md) · [ADRs](docs/adr/)
+**Jump to:** [Demo](#demo) · [Quick start](#quick-start) · [Architecture](#architecture) · [Contributing](CONTRIBUTING.md) · [Security](SECURITY.md) · [ADRs](docs/adr/README.md)
 
 ---
 
@@ -35,7 +35,7 @@ Read the thesis: [`docs/future-of-the-firm.md`](docs/future-of-the-firm.md). Gov
 - **Local demo:** `npm install && npm run build && npm run dev` → [http://localhost:3000](http://localhost:3000)
 - **Regenerate GIF/PNGs:** start the console, then `npm run screenshots` — see [`docs/assets/README.md`](docs/assets/README.md)
 
-Click **Run company day** to watch the agent activity timeline: support → finance → ops handoffs, an autonomous settle, an exception approval path, compensation, and trust unlock.
+Click **Run company day** to watch the agent activity timeline: support → finance → ops handoffs, an autonomous settle, an exception approval path, compensation, and trust unlock. The console sends `autoApproveException: false` so the exception stays in the HITL queue for Approve/Reject.
 
 ---
 
@@ -47,13 +47,25 @@ npm run build
 npm run dev        # ops console on $PORT or 3000
 ```
 
+Contributors and CI should use `npm ci --include=dev` (see [CONTRIBUTING.md](CONTRIBUTING.md)).
+
 ```bash
 npm test
-npm run scenario
+npm run scenario                 # HITL default-off; exits non-zero when exception is not auto-settled
 npm run audit:verify
-./scripts/harness/verify.sh
+./scripts/harness/verify.sh      # functional / static acceptance
+./scripts/harness/adversarial.sh # authorized local adversarial probes (CI also runs this)
+```
+
+### Container
+
+```bash
+docker build -t corpos .
+docker run --rm -p 3000:3000 corpos
 ```
 
+CI may publish images to `ghcr.io/safetymp/corpos` (tags: branch, sha, semver, `latest`). Optional Fly.io deploy runs from [`.github/workflows/deploy.yml`](.github/workflows/deploy.yml) on GitHub release when `FLY_API_TOKEN` is set — see [`fly.toml`](fly.toml).
+
 ## Architecture
 
 | Layer                 | Package / app           | Responsibility                                        |
@@ -65,15 +77,15 @@ npm run audit:verify
 
 Stack: Node ≥22 · TypeScript · npm workspaces · Hono · Drizzle + libsql · official MCP SDK · Preact. No Express, no `better-sqlite3`, no agent-framework lock-in.
 
-Architecture decisions live in [`docs/adr/`](docs/adr/).
+Architecture decisions live in [`docs/adr/README.md`](docs/adr/README.md).
 
 ## Security
 
-Reference architecture — not production-hardened. Set `CORPOS_MODE=shared` and `DASHBOARD_API_TOKEN` before exposing approvals. See [SECURITY.md](SECURITY.md).
+Reference architecture — not production-hardened. `CORPOS_MODE=shared` plus `DASHBOARD_API_TOKEN` enables a **Bearer token gate on the API** for approve/kill mutations. The ops console does not yet attach that token (shared-mode approvals return 401 until a Bearer-capable client is used). See [SECURITY.md](SECURITY.md).
 
 ## Community
 
-[Contributing](CONTRIBUTING.md) · [Code of Conduct](CODE_OF_CONDUCT.md) · [Security](SECURITY.md) · [ADRs](docs/adr/)
+[Contributing](CONTRIBUTING.md) · [Code of Conduct](CODE_OF_CONDUCT.md) · [Security](SECURITY.md) · [ADRs](docs/adr/README.md)
 
 ## License
 
diff --git a/SECURITY.md b/SECURITY.md
@@ -13,16 +13,23 @@ Treat it as a design artifact you can run locally.
 - Shared-mode console sends Bearer (`VITE_DASHBOARD_API_TOKEN` / `DASHBOARD_API_TOKEN`).
 - G3 quorum, G6 appeal, and enforcement `strict`/`audit` modes.
 - Hash-chained audit receipts (`npm run audit:verify`).
+- Company-day demos do not auto-approve exceptions unless a caller passes
+  `autoApproveException: true` (tests/CI only).
 
 ## Not provided
 
 - Full multi-tenant isolation as a security boundary.
 - Production OIDC / TLS by default.
 - Real payment or messaging providers.
+- Live LLM agent execution (health may report `mode: "live"`; company-day still
+  uses `SimulationProvider`).
 
 ## Shared demo
 
-When `CORPOS_MODE=shared`, `DASHBOARD_API_TOKEN` is required for approval and kill mutations.
+When `CORPOS_MODE=shared`, `DASHBOARD_API_TOKEN` is required as a **Bearer**
+token on API approve and kill mutations. The ops console sends
+`VITE_DASHBOARD_API_TOKEN` when configured. This is a
+static token compare for demos, not an OAuth flow.
 
 ## Dependency / supply-chain hygiene
 
@@ -42,4 +49,6 @@ When `CORPOS_MODE=shared`, `DASHBOARD_API_TOKEN` is required for approval and ki
 
 ## Reporting
 
-Use GitHub Security Advisories on the CorpOS repository.
+Use GitHub Security Advisories on the CorpOS repository for **vulnerabilities**.
+Conduct issues are handled under [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md), not
+security advisories.
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,13 @@
+# CorpOS documentation
+
+Public docs for the autonomous-company reference. Not a certification claim.
+
+| Doc | Purpose |
+| --- | --- |
+| [future-of-the-firm.md](future-of-the-firm.md) | Product thesis and 20-minute demo path |
+| [governance-crosswalk.md](governance-crosswalk.md) | NIST AI RMF / OWASP ASI / standards mapping (pedagogical) |
+| [aibom.json](aibom.json) | AI bill of materials inventory |
+| [adr/README.md](adr/README.md) | Architecture decision records |
+| [assets/README.md](assets/README.md) | Regenerating README demo GIF/PNGs |
+
+Contributor setup: [../CONTRIBUTING.md](../CONTRIBUTING.md). Security posture: [../SECURITY.md](../SECURITY.md).
diff --git a/docs/adr/0020-g1-g6-firm-governance.md b/docs/adr/0020-g1-g6-firm-governance.md
@@ -12,3 +12,6 @@ Accepted (corpos-autonomous-company-r3)
 - **G6** one-shot appeal for rejected/TTL-expired exceptions
 
 Agents expose `approverRoles` for quorum membership.
+
+## Consequences
+Bound by site harness verify/adversarial gates. Public docs must not claim coverage beyond what the tree implements.
diff --git a/docs/adr/README.md b/docs/adr/README.md
@@ -0,0 +1,26 @@
+# Architecture decision records
+
+Numbered ADRs for CorpOS. Non-trivial changes that introduce or reverse a
+decision should add or update an ADR (see [CONTRIBUTING.md](../../CONTRIBUTING.md)).
+
+| ADR | Title |
+| --- | --- |
+| [0000](0000-stack-bootstrap.md) | Stack bootstrap |
+| [0001](0001-firm-model.md) | Firm model |
+| [0002](0002-work-contracts.md) | Work contracts |
+| [0003](0003-control-plane.md) | Control plane |
+| [0004](0004-trust-compensation.md) | Trust and compensation |
+| [0005](0005-company-day.md) | Company day |
+| [0006](0006-insight-surface.md) | Insight surface |
+| [0010](0010-orchestrator-task-persistence.md) | Orchestrator task persistence |
+| [0011](0011-provider-strategy.md) | Provider strategy |
+| [0012](0012-unified-firm-store.md) | Unified firm store |
+| [0013](0013-console-hitl-kill-resume.md) | Console HITL, kill, resume |
+| [0014](0014-earned-autonomy-from-outcomes.md) | Earned autonomy from outcomes |
+| [0015](0015-company-day-orchestrator-workload.md) | Company-day orchestrator workload |
+| [0016](0016-positioning-aibom-crosswalk.md) | Positioning, AIBOM, crosswalk |
+| [0017](0017-governance-pdp-pep.md) | Governance PDP/PEP |
+| [0018](0018-three-layer-agentic-authorization.md) | Three-layer agentic authorization |
+| [0019](0019-otel-genai-telemetry.md) | OTel GenAI telemetry |
+| [0020](0020-g1-g6-firm-governance.md) | G1–G6 firm governance |
+| [0021](0021-owasp-asi-adversarial-matrix.md) | OWASP ASI adversarial matrix |
diff --git a/docs/future-of-the-firm.md b/docs/future-of-the-firm.md
@@ -13,7 +13,7 @@ CorpOS is a **reference implementation of an autonomous company**. The thesis:
 
 Interop protocols (MCP, optional A2A later) are **transport**. They do not encode community governance — CorpOS does.
 
-Humans govern **by exception** in the ops console (Approve / Reject / Kill). Autonomy is **earned** from evidence (trust ledger), not granted in prompts.
+Humans govern **by exception** in the ops console (Approve / Reject / Kill). Autonomy is **earned** from evidence (trust ledger), not granted in prompts. Company-day demos keep `autoApproveException` off unless a test/CI caller opts in.
 
 ## 20-minute path
 
diff --git a/docs/governance-crosswalk.md b/docs/governance-crosswalk.md
@@ -22,12 +22,20 @@ Pedagogical mapping only — **not** a certification claim.
 | **G5** decision transparency | Implemented |
 | **G6** appeal / escalation | Implemented |
 
+## Firm governance labels (G1–G6)
+
+| Label | Status in this reference |
+| --- | --- |
+| **G1** membership / agent `active` | Implemented |
+| **G4** dissent on reject | Implemented |
+| G2 / G3 / G5 / G6 | Pedagogical targets in thesis / ADR-20; not fully coded as firm hooks |
+
 ## OWASP Top 10 for Agentic Applications 2026
 
 See Governor `/api/governance` and `scripts/harness/adversarial-run.mjs` ASI cells.
 
 ## Related standards
 
 - ISO/IEC 42001 / EU AI Act Art. 50: transparency records via Governor + audit chain
-- MCP 2025-11-25: elicitation-aligned privileged flows via exception queue; shared demo uses Bearer token
+- MCP 2025-11-25: elicitation-aligned privileged flows via exception queue; shared demo uses Bearer token (`DASHBOARD_API_TOKEN` / `VITE_DASHBOARD_API_TOKEN`), not a full OAuth flow
 - OTel GenAI semantic conventions (Development): span attributes `gen_ai.*`; optional OTLP export
diff --git a/evidence/site-delivery/dossier.md b/evidence/site-delivery/dossier.md
@@ -0,0 +1,18 @@
+# Site delivery note — corpos-autonomous-company-r2
+
+## Summary
+
+CorpOS revised as a July-2026-grade autonomous-company reference:
+orchestrator-driven company day on a shared firm store, console HITL
+(approve/reject/kill), simulation-first providers with honest health `mode`,
+and a governance plane (PDP/PEP, three-layer authz, OTel GenAI, ASI/NIST
+crosswalk, AIBOM).
+
+## Site commands
+
+- `npm run dev`
+- `./scripts/harness/verify.sh`
+- `./scripts/harness/adversarial.sh`
+
+Executable gate evidence: see `receipt.json` and companions in this directory.
+Agents must not self-approve; only the user grants final approval.
diff --git a/fly.toml b/fly.toml
@@ -1,5 +1,5 @@
 # Fly.io config. Deploy with:
-#   flyctl launch --image ghcr.io/safetymp/corpos:0.1.0   (use the published image)
+#   flyctl launch --image ghcr.io/safetymp/corpos:0.2.0   (or :latest / a semver tag)
 #   flyctl deploy                                            (build from the Dockerfile)
 # Or via the deploy.yml workflow with FLY_API_TOKEN set.
 # NOTE: choose a globally-unique app name (flyctl apps create).
diff --git a/package.json b/package.json
@@ -5,6 +5,14 @@
   "description": "CorpOS — reference implementation of an autonomous company",
   "author": "SafetyMP",
   "license": "Apache-2.0",
+  "homepage": "https://github.com/SafetyMP/CorpOS#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SafetyMP/CorpOS.git"
+  },
+  "bugs": {
+    "url": "https://github.com/SafetyMP/CorpOS/issues"
+  },
   "type": "module",
   "workspaces": [
     "packages/*",
diff --git a/render.yaml b/render.yaml
@@ -1,7 +1,6 @@
-# Render Blueprint — one-click deploy of the CorpOS control plane.
-# Click "Deploy to Render" in the README, or: render deploy
-# Runs in simulation mode by default. Live HttpLLMProvider only when
-# OPENROUTER_API_KEY and CORPOS_ALLOW_LIVE=1 are both set.
+# Render Blueprint — optional deploy of the CorpOS control plane (`render deploy`).
+# Runs in simulation mode by default. Live *health reporting* only when
+# OPENROUTER_API_KEY and CORPOS_ALLOW_LIVE=1 are both set (agents stay simulated).
 services:
   - type: web
     name: corpos
@@ -15,5 +14,4 @@ services:
         value: production
       - key: LOG_LEVEL
         value: info
-      # OPENROUTER_API_KEY + CORPOS_ALLOW_LIVE=1 required for live mode
-      # OPENROUTER_MODEL: optional model slug
+      # OPENROUTER_API_KEY + CORPOS_ALLOW_LIVE=1 for health mode=live only
