Skip to main content
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 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.)
  • 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).
  • 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 | LLM Routing | Webhooks HTTP API | Procedures HTTP API | Approval Lifecycle