docs: add contextweaver + agent-kernel reference flow for policy-before-action

[dgenio]

Context

contextweaver and agent-kernel solve adjacent parts of the same runtime problem:

• contextweaver narrows what the model sees: tool cards, compiled context, summarized tool results.
• agent-kernel should enforce what the agent is allowed to do: capabilities, policy, audit, and authorization boundaries.

For ecosystem clarity, the two projects need a concrete reference flow showing that routing/context selection is advisory and policy enforcement still happens before execution.

Goal

Add a docs/reference example showing a tool-using agent flow where:

1. contextweaver builds a small candidate/tool-card shortlist.
2. the model or host selects an intended action.
3. agent-kernel checks the action against capability/policy rules.
4. only approved actions proceed to execution.
5. denied or ask-for-confirmation decisions are represented clearly.

Proposed files

• docs/integrations/contextweaver.md
• optional examples/contextweaver_policy_flow.py

Acceptance criteria

• The docs clearly state that contextweaver routing does not grant permission.
• The example includes at least three outcomes: allow, ask/confirm, deny.
• The example uses synthetic data only and runs without external services.
• The flow references Weaver-compatible routing/execution concepts where useful.
• README links to the integration page from an ecosystem/interoperability section.

Related

• Align contextweaver routing outputs with Weaver routing contracts contextweaver#320
• Define generic RoutingDecision and ExecutionFeedback contracts weaver-spec#61

[dgenio]

Closing as completed — implemented and merged via PR #101 (commit e23e324).

The merged work satisfies every acceptance criterion:

• Routing ≠ permission stated explicitly — docs/integrations/contextweaver.md opens with "Routing is advisory. Selection is not permission." and shows the full policy → token → invoke → firewall → trace pipeline running after selection.
• ≥3 outcomes (allow / ask-confirm / deny) — examples/contextweaver_policy_flow.py demonstrates all three. Since PolicyDecision is binary, ask is derived from the recoverable INSUFFICIENT_JUSTIFICATION denial code while MISSING_ROLE is terminal.
• Synthetic data, no external services — the example runs offline and does not import contextweaver; it's wired into the example target in Makefile so it executes under make ci.
• Weaver concepts referenced — tool cards → Capability/CapabilityDescriptor, selection → CapabilityRequest, and the resulting ActionTrace is mapped to weaver-spec invariant I-02.
• README links the page — README.md and docs/integrations.md ("Ecosystem integration patterns") both link the new page and companion example.

If anything in the delivered flow looks off, feel free to reopen.

---

Generated by Claude Code