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.
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 legacywriteArtifact 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 ofarchitecture/writeartifact) — full rewrite for the unified files/bindings model. CoversputFile(discriminatedsource × bind),getFile(three modes:text/sandbox/meta), thefileIdcontract enforced bygenerateObject, 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-tiermodelRoutingConfig,llmFallbackChains, andmodelSlotsinfrastructure. -
architecture/flows/approval-lifecycle— new “Unified Human Interaction model” section: approvals are now one of four scopes (approval | question | confirmation | form) that sharehumanInteractionRequestsfor fan-out, recall, and callback. Theapprovalstable 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. TheputFile/getFilewire 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 (workflowInputslegacy +workflowInputSchemacanonical, 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 byForgeClient2.2.0 (procedure endpoints and the LLM proxy are deliberately out of scope;getInputSchemaand 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 to0.5.0. Added path entries forworkflows/get-input-schema, the four webhook routes, and the three procedure routes. AddedWebhooksandProcedurestags. (The OpenAPI spec was four weeks stale at the start of this cut; this is the catch-up.)
Nav + housekeeping
forge-nav.jsonupdated:writeartifactremoved,files-and-bindingsadded in its place;llm-routingadded under Architecture; new HTTP API groups for Webhooks and Procedures;getInputSchemaadded to the Workflows group; 2026-05-27 changelog entry added at the top of Weekly Entries.lastUpdatedandappliesToVersionset to2026-05-27on 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. StandardizedJudgeVerdictV1shape, the eight platform-shipped Judges, findings +suggestedActiondeep-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 replacesgateChatResponsefor 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_JSONsize cap andINPUT_TOO_LARGEpreflight, 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
lastUpdatedrefreshed across the use-case set with light reverification. Theai-intake-pipelineuse case was confirmed against the recent demo update path (/platform/external-apps).
Nav + housekeeping
forge-nav.jsonupdated with all new pages: concepts (5), architecture (4), run (4), build (1), reference (2).lastUpdatedandappliesToVersionset to2026-05-27on every new / touched file.
Decisions worth noting
POST /api/v2/agents/deploy,/undeploy,/listDeployments— the plan asked for dedicated reference pages. The live handlers return501 Not Implemented(theagentDeploymentstable was removed earlier; agent state changes take effect on the next dispatch viacomposeAgentConfig). 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 | LLM Routing | Webhooks HTTP API | Procedures HTTP API | Approval Lifecycle

