[Feature]: Build a complete Examples Gallery covering every `agentmesh` module

[aditisingh02]

Package

agent-governance

Problem Statement

The Go module exposes 13 distinct governance subsystems in
agent-governance-golang/packages/agentmesh — identity, trust, policy, external
policy backends, audit, MCP security, execution rings, kill switches, lifecycle,
SLOs, framework integrations, shadow discovery, and prompt defense — but
examples/ currently ships only three runnable demos:

agent-governance-golang/examples/
├── http-middleware/
├── quickstart/        ← added recently (commits 35378b03, 2460c52b)
└── slo-tracking/

Every other module is reachable only through the README's API tables and the
Go reference site. That creates three concrete problems for adopters:

1. High time-to-first-success. A developer evaluating AgentMesh has to read
   source code to figure out how to wire most subsystems together. The unified
   NewClient is well-covered; everything else is not.
2. README snippets aren't compile-checked. The code blocks in the module
   README live outside CI. The new examples/quickstart/ pattern proved we can
   keep snippets honest by linking to a runnable directory — but we've only
   applied that pattern to one module.
3. Composition stories are invisible. The interesting parts of this toolkit
   are interactions — kill switch + policy fail-closed semantics, lifecycle
   gating capability grants, trust scoring feeding into ring assignment, OPA/
   Cedar fallback when the remote evaluator is down. Examples are the only
   place these stories land, and we have none of them today.

A related, time-sensitive gap: the fail-closed HTTP middleware migration
documented in agent-governance-golang/README.md (the
LegacyTrustedHeaderAgentIDResolver section) needs a worked example wiring
AgentIDResolver to a real authenticated front door. Without one, users
delaying the migration have no concrete reference to follow.

Proposed Solution

Add a complete, compile-checked Examples Gallery: one focused example per
public module, each runnable with go run ., each linked from the README, and
each swept by CI so they cannot rot.

Scope — one example directory per uncovered module

Each new directory contains main.go plus a short README.md and uses only
the public API surface.

Module	Status	Proposed example	Demonstrates
client.go	✅ examples/quickstart/	—	—
middleware.go	✅ examples/http-middleware/	—	—
slo.go	✅ examples/slo-tracking/	—	—
identity.go	❌	examples/identity-sign-verify/	Generate identity, sign payload, verify signature, round-trip via ToJSON/FromJSON
trust.go	❌	examples/trust-scoring/	Asymmetric reward/penalty, decay over time, fail-closed VerifyPeer
policy.go	❌	examples/policy-yaml/	LoadFromYAML, wildcard + condition matching, Allow/Review/Deny outcomes
policy_backends.go	❌	examples/policy-opa-cedar/	LoadRego + LoadCedar, remote vs built-in modes, fail-closed on backend error
audit.go	❌	examples/audit-chain/	Append entries, tamper a record, demonstrate Verify() catching the break
mcp.go	❌	examples/mcp-scan/	Scan benign + poisoned + typosquat tool definitions, show risk scores
rings.go	❌	examples/execution-rings/	Assign Ring 0–3, custom ring permissions, deny escalation
kill_switch.go	❌	examples/kill-switch-scopes/	Global vs agent vs capability scopes, activation history, DecisionFor resolution
lifecycle.go	❌	examples/lifecycle-transitions/	Full provisioning → active → suspended → quarantined → decommissioned walk, plus one rejected invalid transition
discovery.go	❌	examples/shadow-discovery/	ScanText, ScanProcesses, ScanConfigPaths against a fixture tree
promptdefense.go	❌	examples/prompt-defense/	Score benign, indirect-injection, and exfil prompts; show structured findings
Composition	❌	examples/full-stack/	One agent goes through identity → trust → ring → policy → kill-switch → audit → SLO end-to-end
Migration	❌	examples/http-middleware-fail-closed/	Walks the LegacyTrustedHeaderAgentIDResolver → verified AgentIDResolver migration with a worked reverse-proxy example

Acceptance criteria

• Each new example lives under agent-governance-golang/examples/<name>/.
• Each example is a standalone package main and matches the structural
  convention already established by examples/quickstart/ (no new
  patterns introduced).
• Each example directory contains a README.md with: one-paragraph intent,
  the command to run it, and the expected output (or a representative slice).
• go build ./... and go vet ./... succeed from the module root and are
  exercised by CI on every PR. Extend .github/workflows/ci.yml if the
  examples are not already swept in.
• The top-level agent-governance-golang/README.md "API Overview" tables
  gain an "Example" column linking to the relevant directory.
• No example uses LegacyTrustedHeaderAgentIDResolver except the
  explicit migration example, which must call out in its README that the
  resolver is a compatibility bridge, not a recommended default.
• No example silently swallows errors. log.Fatal on setup failure is
  fine; _ = err is not.

Alternatives Considered

Split into 11 separate issues, one per example. Rejected as the primary
form, because the dependency ordering between phases (and the shared
acceptance criteria around CI + README cross-links) only makes sense in one
place. Happy to split if maintainers prefer — the scope table above is the
unit of work either way.

Embed expanded snippets directly in the module README instead of examples/
directories. Rejected because README code blocks aren't compile-checked.
The whole point of the examples/quickstart/ pattern is that CI catches
drift; in-README snippets recreate the problem this issue is trying to solve.

Generate examples from the test suite. Tempting, but tests optimise for
coverage and edge cases, not for narrative clarity. A new adopter reading a
test file learns what the module guards against, not how to use it. Examples
need to be written as examples.

Wait until each module has a "killer demo" use case and write only those.
Rejected because it leaves adopters guessing for every module without one,
and "killer demo" is a moving bar. A minimal, honest example per module is
strictly better than zero examples for most modules and one polished demo
for a few.

Priority

Nice to have

Contribution

• I would be willing to submit a PR for this feature

[github-actions]

🤖 AI Agent: contributor-guide

Hi @first-time-contributor! 👋 Thanks for your detailed issue. This request is relevant to the agent-governance package, specifically the agentmesh modules. Your proposal for a comprehensive Examples Gallery is well-structured and aligns with the project's goals. To get started, please review our CONTRIBUTING.md for guidance. Let us know if you have any questions! 🚀

[github-actions]

🟡 Contributor Check: MEDIUM

Check	Result
Profile	MEDIUM
Credential	NONE
Overall	MEDIUM

Automated check by AGT Contributor Check.

[Ricky-G]

@aditisingh02 this is great, please go ahead and do the examples as a PR