docs: full sync sweep v0.17.1→v0.18.1 + rolling anchor

[initializ-mk]

Full documentation sweep — everything merged v0.17.1 → v0.18.1 (120 commits / ~42 PRs), not just one branch. Driven by 5 parallel domain audits (MCP+auth, security/egress/governance, CLI/skills, LLM/runtime/memory, channels/audit/observability) that mapped each merged feature to its docs and flagged MISSING / STALE.

Also introduces a rolling anchor (docs/sync-docs-state.md) so future /sync-docs runs are incremental — the next sweep only diffs 2f0649e..main instead of re-scanning history.

Gaps found and filled (17 files)

Reference / schema (the biggest gaps — the canonical reference lagged the feature waves):

• forge-yaml-schema.md — added the entire mcp: block (auth types oauth/bearer/static/platform/user, grant, token_env/client_secret_env, tenancy, ${VAR}), the apis: per-op API-tool block (feat(tools): per-operation API tool type from admitted OpenAPI entries #400), the pdp: block (feat(runtime): managed PDP decision resolver at BeforeToolExec #399), egress allowed_tcp + allowed_private_cidrs, and defer approvers.
• cli-reference.md — added the missing forge mcp list/test/login/logout section and the startup version banner (Startup banner: print the forge binary/runtime version (and commit) #335/feat(cli): show forge binary/runtime version on the startup banner (#335) #336).

Audit catalog:

• audit-logging.md — added llm_call_failed (Emit llm_call_failed audit event on LLM error path — failed calls are invisible to audit #361) and mcp_auth_required/resolved/timeout (Auth-required gate: DEFER park/resume for delegated MCP consent (#317 follow-up) #330/MCP consent/egress audit events lose invocation attribution (unattributed correlation_id/task_id) #366) to the event catalog; documented always-on fields.error redaction (Skill tool schemas: parse the platform Input format correctly; validate property keys at registration #362), channel-sender attribution on auth_verify (Attribute channel-originated tasks to the human sender (§19 P3 delegated identity) #356), and llm_call.url userinfo stripping (feat(llm): apikey_header_only auth scheme + record invoked LLM URL on llm_call #358).

Stale corrections:

• defer-decisions.md — the runtime: detach task execution from the request so deferrals survive #402 task-detach: the deferred task now survives a caller disconnect (was documented as "abandoned / cap timeout ≤ 6m").
• tools-and-builtins.md — removed the deleted openapi_call adapter; documented per-op apis.servers → <name>__<op> tools.
• memory-system.md — the remote session store attaches independent of memory.persistence (Streaming (tasks/sendSubscribe) invocations don't persist sessions — channel/widget agents show no executions #372/Build the remote session store independent of the memory.persistence gate (#372) #373) — was implying persistence: true is required.
• skill-md-format.md / writing-custom-skills.md — fixed stale "runs via bash" → per-interpreter (.py→python3, .js→node; feat(cli): convert a SKILL.md folder (scripts + reference files) into a runnable Forge agent #405 D2).
• .claude/skills/forge.md — de-staled R10 (delegated identity): "proposed / not implemented" → implemented, with correct event names (was misleading the agent's own reasoning).

New / expanded sections:

• platform-policy.md — new managed PDP section (feat(runtime): managed PDP decision resolver at BeforeToolExec #399, per-call authz at BeforeToolExec, fail-closed).
• channels.md — Slack raw-JSON suppression + <<ctxzip:…>> marker stripping across Slack/Telegram/Teams + response.Summary (fix(channels): stop dumping raw tool JSON to Slack; keep chunks in-thread #384).
• tenancy.md — platform-callout Org-Id/Workspace-Id header contract.
• mcp/ — de-staled the "seven events" framing + consent-gate events; tool-name regex ^[a-zA-Z0-9_-]{1,128}$ (fix(validate): accept hyphenated MCP tool names in allow/deny lists #370); delegated-token 5-min TTL cap (Delegated MCP token cache ignores platform disconnect — revoked grant keeps working for the token lifetime (~1h) #380).

Verification

Broken-link check clean across all changed docs. .claude/skills/forge.md TOC unaffected (row/prose edits only). Every claim traced to code by the audits (file:line in the audit trail).

What's intentionally NOT here

Pure bug fixes with no user-facing doc surface (e.g. Windows OAuth launch #312) and features already documented + verified accurate (forge try, skill import, data-part prompt, session-recovery dedup, SOCKS5 egress, DEFER approvers, denied_command_patterns).

[initializ-mk]

Review — docs sync sweep (v0.17.1 → v0.18.1)

Docs-only (all 17 files .md); CI green including the broken-link check. For a docs PR the risk is a wrong claim, so I spot-checked the highest-value ones — security-relevant, schema, and agent-facing — against the code (leaning on my reviews of these features and verifying two I hadn't). Everything I traced is accurate:

• pdp: schema — enabled/endpoint/fail: closed, "env-expanded at load" (the exact #399 fix), single-decision-source, and precisely "every governed tool call" (correctly reflects the #401 builtins-skip, not a lazy "every tool call"). ✓
• apis: schema — base_url (allowlisted), token_env "oauth rejected for apis", operations[].{method,path} with {account_id} templating (#400). ✓
• Egress allowed_tcp / allowed_private_cidrs; defer detach #402 correctly replaces the stale "abandoned / cap ≤6m"; delegated-token 5m TTL. ✓
• MCP tool-name regex ^[a-zA-Z0-9_-]{1,128}$ (#370) — present in forge-core/validate/mcp_config.go. ✓
• Rolling anchor 2f0649e resolves and is conservatively set to the audited HEAD, so the next incremental sweep diffs correctly. ✓

Scope note (transparency, not a finding): this is a spot-check weighted to the security/schema/agent-facing claims — 100% accurate in my sample — not a line-by-line trace of all 258 lines; the prose-heavy channels/memory/observability details I sampled but didn't exhaustively verify. Confidence is high given the sample and the audits' file:line trail.

One high-value correction called out inline. Approve-grade — nothing blocking.

[initializ-mk]

Verified this agent-facing correction is accurate — and it's the most valuable edit in the sweep, because the old text was actively misleading the agent's own reasoning:

• "R10 delegated identity: proposed / not implemented" → implemented matches the Auth-required gate: DEFER park/resume for delegated MCP consent (#317 follow-up) #330/Epic: runtime per-user, ephemeral per-session MCP OAuth (interactive login via Slack / A2A UI) #317/fix(mcp): route call-time ErrNoToken through the auth gate (closes #376) #377/fix(runtime): dedup only a trailing identical user turn on session recovery (closes #378) #379/fix(mcp): cap delegated token cache TTL so a disconnect is enforced (#380) #381 delegated-auth arc that's on main.
• The audit event names change from the never-shipped planned names (mcp_auth_requested/completed/denied) to the real constants: forge-core/runtime/audit.go defines exactly mcp_auth_required / mcp_auth_resolved / mcp_auth_timeout, and mcp_authgate.go confirms the MCP consent/egress audit events lose invocation attribution (unattributed correlation_id/task_id) #366 single-emit-no-duplicate behavior the row now describes.

Good catch de-staling this — a wrong event name in the agent's own skill doc is worse than a wrong name in user docs. 👍