> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gloo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Week of 2026-05-27 — Docs refresh: foundations, reference, and new concepts

> Two-cut docs refresh — foundations & reference (first cut) plus new concepts (second cut: Procedures, Judges, JIT Synthesis, Workflow Architect, Personal Agents) and the use-case audit pass.

**2026-05-27**

Two-cut docs refresh — foundations & reference plus new concepts (second cut: Procedures, Judges, JIT Synthesis, Workflow Architect, Personal Agents) and the use-case audit pass.

Last updated 2026-11-11

·
applies to 2026-05-27

·
main

## Summary

First of two docs-refresh cuts (foundations & reference layer). This cut closes the documentation gap for capabilities that have shipped since the last audit: the unified files/bindings model that replaced the legacy `writeArtifact` quartet, the LLM routing tier abstraction extracted from inference, the unified Human Interaction table behind approvals, and HTTP API surface for procedures, webhooks, and workflow input-schema introspection. The second cut of the refresh (new concept pages for Judges / JIT Synthesis / Procedures-as-concept / Workflow Architect / Personal Agents, plus the use-case audit) will follow.

## What's new

### Architecture

* **`architecture/files-and-bindings`** *(rename of `architecture/writeartifact`)* — full rewrite for the unified files/bindings model. Covers `putFile` (discriminated `source × bind`), `getFile` (three modes: `text` / `sandbox` / `meta`), the `fileId` contract enforced by `generateObject`, and a one-row migration table from the legacy quartet (`writeArtifact`, `readArtifact`, `copyFileToSandbox`, `importFileFromSandbox`) to the unified surface.

* **`architecture/llm-routing`** *(new)* — the tier abstraction (`nano | low | mid | high | frontier`) and its four-stage resolution pipeline (`staticResolve` → `dynamicAdjust` → `selectProvider` → `dispatchTelemetry`). Documents the deliberate coexistence with the legacy three-tier `modelRoutingConfig`, `llmFallbackChains`, and `modelSlots` infrastructure.

* **`architecture/flows/approval-lifecycle`** — new "Unified Human Interaction model" section: approvals are now one of four scopes (`approval | question | confirmation | form`) that share `humanInteractionRequests` for fan-out, recall, and callback. The `approvals` table remains as the domain-specific projection.

### Reference (HTTP API)

New domain pages plus per-endpoint references — every route was verified against the route registry:

* **Webhooks** (`/api/v2/webhooks` × POST/GET/DELETE + `POST /api/v2/webhooks/rotate-secret`) — domain index plus four endpoint pages. Documents the five-event taxonomy (`approval.requested | approval.sla_breached | approval.resolved | workflow.started | workflow.completed`), HMAC-SHA256 signing, at-least-once delivery semantics, and the "secret returned exactly once" lifecycle.
* **Procedures** (`/api/v1/proceduresApi/{invokeCapability,putFile,getFile}`) — domain index plus three endpoint pages. Sandbox-facing surface authenticated by per-dispatch session token. The `putFile` / `getFile` wire shapes are the JSON serialization of the agent-tool input schemas — same authorization model, same discriminated unions.
* **Workflows / `getInputSchema`** (`GET /api/v2/workflows/get-input-schema`) — new endpoint page covering the Phase 2 widen window (`workflowInputs` legacy + `workflowInputSchema` canonical, returned in parallel).

### Reference (existing pages updated)

* **`reference/inference`** — split into two clearly demarcated surfaces. The External App carve-out at `/api/inference/v1/*` (JWKS-signed JWT, third-party SDK compat) and the LLM proxy at `/api/llm/v1/*` (virtual-key bearer, internal routing through the tier abstraction). The two were previously conflated as one "inference" surface.
* **`reference/typescript-sdk`** — added an "Endpoints not yet in the typed client" table. Every entry was verified against the route registry; none of the new surfaces are wrapped by `ForgeClient` 2.2.0 (procedure endpoints and the LLM proxy are deliberately out of scope; `getInputSchema` and webhooks will be wrapped in a follow-up).
* **`reference/mcp-server`** — added the equivalent "Endpoints not yet exposed as MCP tools" table.
* **`reference/openapi.json`** — bumped to `0.5.0`. Added path entries for `workflows/get-input-schema`, the four webhook routes, and the three procedure routes. Added `Webhooks` and `Procedures` tags. (The OpenAPI spec was four weeks stale at the start of this cut; this is the catch-up.)

### Nav + housekeeping

* `forge-nav.json` updated: `writeartifact` removed, `files-and-bindings` added in its place; `llm-routing` added under Architecture; new HTTP API groups for Webhooks and Procedures; `getInputSchema` added to the Workflows group; 2026-05-27 changelog entry added at the top of Weekly Entries.
* `lastUpdated` and `appliesToVersion` set to `2026-05-27` on every touched file.

## Second cut — new concepts and operator surfaces

The second cut of the refresh adds the new-concept layer and the operator-facing surfaces that came online since the last audit:

### Concepts (new)

* **`concepts/procedures`** — first-class workflow primitive. Typed I/O, closed error vocabulary, capability declarations, pinned image digests, dual exposure as graph node + agent tool.
* **`concepts/judges`** — verdict-emitting agents. Standardized `JudgeVerdictV1` shape, the eight platform-shipped Judges, findings + `suggestedAction` deep-links, calibration + drift.
* **`concepts/jit-synthesis`** — search-first reuse, three Builders, the Coherence Gate panel, Provisional-First Reuse, cross-Architect dedup, workspace synthesis budget, the Curator.
* **`concepts/workflow-architect`** — propose-plan / confirm handshake, read-only narrowing during confirmation, the seven topology shapes, the Architect Judge's five-criterion rubric.
* **`concepts/personal-agents`** — one agent per human worker, auto-provisioned, runs under the human's principal identity. Anti-hallucination through first-class capabilities and skill-composed prompts.

### Architecture (new)

* **`architecture/judges-engine`** — dispatch lifecycle, the verdict-schema gate that replaces `gateChatResponse` for Judges, the Architect subject builder, the nightly metrics cron, panel admissions, per-workspace settings.
* **`architecture/synthesis-pipeline`** — the six-stage pipeline (search → request → reserve → Builder → Coherence Gate → reconcile / Curate). Per-stage tables, reservation + reconciliation.
* **`architecture/procedures-subsystem`** — four-stage subsystem (registration → snapshot composition → executor → capability proxy). Pinned image digests, `GLOO_PROCEDURE_INPUTS_JSON` size cap and `INPUT_TOO_LARGE` preflight, dual graph-node + agent-tool dispatch.
* **`architecture/procedure-governance-gates`** — the eleven-gate Trust Fabric pipeline for procedure dispatches, with the two procedure-specific gates (`gateCapabilityAllowlist`, `gateEgressAllowlist`).

### Run (new)

* **`run/webhooks`** — operator-facing subscription lifecycle: AES-256-GCM secret storage, Splunk HEC format, HMAC signing, `idempotencyKey`, the replay affordance (`replayedFrom`).
* **`run/judges-and-verdicts`** — calibration loop, override behavior, per-workspace mute/demote/scope, rate-this-run, drift alerts.
* **`run/synthesis-budgets-and-curator`** — the monthly cap with reservation + reconciliation, alert thresholds, the Curator review queue (pending, auto-deprecate, duplicate suggestions), Synthesis Templates.
* **`run/planning-and-goals`** — Roadmaps → Workstreams → Milestones → Objectives, Blockers, the Critical Path view with transitive conflict badges, I-Could-Help.

### Build (new)

* **`build/author-a-judge`** — write the rubric skill, register the agent, wire the dispatch site, calibrate. The judge-architect rubric is the canonical template.

### Reference (new)

* **`reference/procedure-sdk-node`** — full surface for `@gloo/procedure-sdk-node`. Boot env, `invokeCapability`, `putFile`/`getFile`, `runProcedure`, `emitProgress`, error codes.
* **`reference/procedure-sdk-python`** — Python sibling, including the codegenned `_generated/` Pydantic models and the drift-enforcement test.

### Knowledge-base / use-cases

* `lastUpdated` refreshed across the use-case set with light reverification. The `ai-intake-pipeline` use case was confirmed against the recent demo update path (`/platform/external-apps`).

### Nav + housekeeping

* `forge-nav.json` updated with all new pages: concepts (5), architecture (4), run (4), build (1), reference (2).
* `lastUpdated` and `appliesToVersion` set to `2026-05-27` on every new / touched file.

## Decisions worth noting

* **`POST /api/v2/agents/deploy`, `/undeploy`, `/listDeployments`** — the plan asked for dedicated reference pages. The live handlers return `501 Not Implemented` (the `agentDeployments` table was removed earlier; agent state changes take effect on the next dispatch via `composeAgentConfig`). Because these surfaces are unreachable, no per-endpoint pages were created — the existing note on the Agents HTTP API page already documents the retirement, and the SDK / MCP notes flag them explicitly.

***

*See also: [Files and Bindings](https://docs.gloo.com/forge/architecture/files-and-bindings.md) | [LLM Routing](https://docs.gloo.com/forge/architecture/llm-routing.md) | [Webhooks HTTP API](https://docs.gloo.com/forge/reference/http-api/webhooks) | [Procedures HTTP API](https://docs.gloo.com/forge/reference/http-api/procedures) | [Approval Lifecycle](https://docs.gloo.com/forge/run/approvals-and-hitl.md#approval-lifecycle)*


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.