docs: dedicated pages for managed PDP (#399) and per-operation API tools (#400)

[initializ-mk]

Follow-up to the full docs sweep (#416), which brought two managed-governance subsystems from undocumented to minimally documented. Both now have a schema block + a short section, which is enough to discover and configure them — but each is a substantial subsystem that warrants a dedicated page once it stabilizes / grows.

1. Managed PDP (Policy Decision Point) — #399

Current coverage: a pdp: block in docs/reference/forge-yaml-schema.md and a "Managed PDP" section in docs/security/platform-policy.md.

What a dedicated page (docs/security/policy-decisions.md or pdp.md) should add:

• The decide-request/response wire contract (what Forge POSTs to endpoint, what a verdict looks like: allow / deny / modify, and how modify rewrites args).
• Where it sits relative to the other R4 controls (intent alignment R3 → step-up R4b → MODIFY R4a → the PDP/DEFER decision → tool executes) and how it composes with / replaces the static security.defer map.
• The audit trail of a PDP decision (which event, invocation_id attribution, deny/modify fields) — cross-link audit-logging.md.
• Fail-closed behavior end-to-end (unreachable/slow PDP, timeout, malformed verdict) and the §14.5 rationale.
• A platform-integrator runbook: standing up a PDP endpoint, the bearer + Org-Id/Workspace-Id callout contract, and a worked allow/deny/modify example.
• Scope precisely: which tools are governed (namespaced <server>__<op> / <name>__<op>) vs. builtins/scripts.

2. Per-operation API tools — apis.servers — #400

Current coverage: an apis: block in docs/reference/forge-yaml-schema.md and a "Per-operation API tools" subsection in docs/core-concepts/tools-and-builtins.md.

What a dedicated page (or an expanded section) should add:

• The full APIServer/APIOp shape: operations[].input_schema (how the OpenAPI arg schema maps to the tool's typed input), {path} templating substitution rules, method/verb handling, and the per-op description.
• How entries are platform-materialized from admitted OpenAPI specs (the admission → apis.servers[] path) vs. hand-authored.
• Auth: bearer/static via token_env (and why oauth is rejected for API entries).
• Egress: the base_url host must be on the allowlist; how it interacts with the egress enforcer.
• PDP/governance: because each op is its own <name>__<op> tool, rules key per operation — worked example.
• Migration note for anyone who used the removed openapi_call generic adapter.

Acceptance

• A dedicated PDP page (or a substantially expanded platform-policy section) covering the wire contract, composition with R3/R4b/R4a/DEFER, audit, and a platform runbook.
• A dedicated / expanded API-tools page covering input_schema, path templating, materialization, auth, egress, and PDP interaction.
• Both linked from the relevant indexes (security overview, tools-and-builtins) and the README doc table.
• /sync-docs mapping updated so forge-cli/runtime/pdp_resolver.go / forge-core/types/config.go (APIConfig/PdpConfig) and forge-core/tools/adapters/*api* map to the new pages.

Refs

• Sweep PR: docs: full sync sweep v0.17.1→v0.18.1 + rolling anchor #416. Schema/section coverage lives there.
• Code: forge-cli/runtime/pdp_resolver.go, forge-core/types/config.go (PdpConfig, APIConfig/APIServer/APIOp/APIAuth), forge-cli/build/tools API adapter (adapters.NewAPITool).
• Governance context: Agent runtime governance compliance (R1–R9): tracking + gap analysis #216 (R-series), feat(runtime): managed PDP decision resolver at BeforeToolExec #399, feat(tools): per-operation API tool type from admitted OpenAPI entries #400.