# Sage Integration Brief

Date: 2026-05-21  
Scope: safe use of `bez111/sage-widget` inside ErgoCommunity.org.

## Source Reviewed

- Repository: https://github.com/bez111/sage-widget
- Package: `@ergoblockchain/sage-widget`
- Official demo: https://www.ergoblockchain.org/agent-economy#sage-activity
- Public activity API: https://www.ergoblockchain.org/api/sage/activity

The widget package ships React and vanilla mounts for a read-only Sage activity feed and a paid Sage chat flow. It also exposes typed clients for quote, payment verification, chat stream, receipt bundle and activity feed.

## Product Decision

Ship the read-only Sage proof stream first.

Do not ship the paid Sage chat flow in public V1.

Reason: the activity feed strengthens the portal's proof theme without asking visitors to perform wallet, Note, payment or verification actions inside a community-run site. Paid chat should wait until the source registry, safety interstitials and testnet/mainnet boundary copy are production-ready.

## V1 Integration

Use Sage as a proof pattern:

- public activity feed
- receipt links
- machine-readable receipt API
- testnet/mainnet state
- no wallet prompt
- no seed/private-key flow
- no payment instruction in the community portal

Production can either:

- use the hosted iframe drop-in at `https://www.ergoblockchain.org/agents.js`,
- install `@ergoblockchain/sage-widget` and mount the vanilla/React activity feed, or
- fetch `https://www.ergoblockchain.org/api/sage/activity` server-side and render a custom portal-native feed.

The current prototype uses the hosted iframe drop-in with a fallback state for local preview.

If production adds a Content Security Policy, allow the hosted drop-in explicitly:

- `script-src https://www.ergoblockchain.org`
- `frame-src https://www.ergoblockchain.org`
- `connect-src https://www.ergoblockchain.org` if a server/client activity API integration is used

## Later Gate

Paid Sage chat requires:

- approved-source index
- clear official/community boundary
- safety-reviewed payment copy
- explicit testnet/mainnet state
- receipt privacy review
- support escalation path
- no wallet signing inside the portal

## Why It Matters

ErgoCommunity.org should make useful work visible. Sage demonstrates the same philosophy in a technical domain: a real action produces a public receipt, and that receipt can be linked, verified and understood without relying on marketing claims.

The portal can reuse this pattern for community contributions:

- task claimed
- artifact shipped
- reviewer confirms
- receipt created
- Pulse recognizes the result
- next task is routed