Fgentic documentation

Fgentic is the A2A appservice for Matrix: @mention an agent in any room, governed. matrix-a2a-bridge turns a mention into an A2A delegation — to an agent on your own Kubernetes cluster, or to an explicitly pinned remote agent in another organization — and posts the reply back as that agent's ghost user. It installs into a homeserver you already run; the full sovereign stack around it is the reference distribution that proves it in context, not something you have to adopt whole. Every critical collaboration layer is an open protocol or a genuinely open-source component, the model backend is a per-cluster choice, and organizations can federate so agents collaborate across company boundaries. Stock Element X background notifications remain an explicit external metadata path through Element and APNs/FCM; production.md records that accepted residual and its exit.

To try the reference distribution, clone the repository and run mise trust && mise run demo:up — no cloud account and no model key. How long it takes is dominated by pulling roughly 10 GiB of container images; a measured range on named hardware is being captured with the demo recording. The README has the prerequisites.

These pages are the specification and the runbooks. Markdown under docs/ is canonical; this site is rendered from it. Topic specs preserve the §N numbering of the retired root SPEC.md (mapping in .agents/AGENTS.md).

New here

• Architecture & Vision - what Fgentic is, why it matters, and the end-to-end architecture (§1–§3, §11)
• Open Agentic Stack - governance, protocol boundaries, and current reuse across the independently stewarded layers
• Design Decisions D1–D20 - the durable register of settled decisions with evidence (§4)
• Roadmap - phase history and the mapping to dated GitHub milestone snapshots (§13)

Evaluating or adopting

• Sovereign Agent Platform Reference Architecture - vendor-neutral requirements matrix, architecture views, evidence boundaries, and copy-ready RFP checklist
• Adopter Decision Brief - vendor-neutral procurement decision and parameterized TCO worksheet
• Competitive Landscape - dated, source-bound comparison with open and commercial alternatives, including where Fgentic loses today
• Persona Onboarding - role-specific paths for security leads, DPOs, platform engineers, developers, and end users
• Incumbent Chat Coexistence - choose whether to run Fgentic beside, bridge with, or migrate from an existing chat system
• Inbound Migration Guide - staged authorization, data, cutover, rollback, and decommission path from a tenant-anchored agent platform
• Exit Strategy - per-layer replacement targets, migration boundaries, one-way doors, and required exit evidence
• Public Surface Stability Contract - stability tiers for surfaces partners pin
• A2A Conformance Currency - current protocol/SDK baseline, upstream watch signals, and adoption checklist
• LF AI & Data Sponsor Map - dated member candidates, Associate route checks, and the one-quarter no-sponsor fallback
• CNCF Sandbox 2028 Second-Credential Dossier - dated evidence and copy-ready answers for a conditional review after LF AI & Data acceptance

Installing and operating

• Evaluating and Developing Locally - model-provider choice, cache and teardown behavior, the federation lab lifecycle, the development loop, and the coding-agent bootstrap
• Production Installation - Flux-reconciled production path with SOPS secrets and acceptance gates
• Air-gapped & Registry-Mirrored Installation - populate a private OCI mirror from the release BOM, redirect pulls at the node, reconcile Flux, and the residual egress that remains
• Adopter Release & Upgrade Contract - tag = tested pin-set, the machine-readable BOM, upgrade notes, and the Flux tag-tracking flow
• Day-2 Operations Handbook - evidence-bound monitoring, scaling, recovery, incident, and upgrade procedures
• GKE Demo Cost Model - dated per-line cost table, the layered spend ceiling, and the availability a Spot node actually buys
• Reading the Cost Dashboards - interpreting aggregate tokens, delegation pressure, partner reservations, and unavailable attribution
• Ketesa Administrator Console - opt-in deployment, authorization acceptance, five operator tasks, and zero-footprint removal
• Moderation Stack - opt-in Draupnir policy-list bot, shared policy room, power-level ordering, and reported-events review
• Retention and Data-Subject Erasure - finite Matrix policy, store-by-store limits, and the honest MAS-to-Synapse workflow
• Delegation Attribution Audit - proving who invoked which agent, when, over which model path
• Bridge Performance Evidence - dated load-sanity evidence for §12.5
• Demo Recording - capture, disclosure, secret-review, and publication contract for the 30-second proof-of-life media

How it works

• Bridge Specification - behavioral contract of the Matrix-to-A2A bridge appservice (§5, §6, §12)
• Encrypted-Room Intake Design - why Megolm intake breaks the pre-acknowledgement job contract, what replaces each invariant, and the cost of ADR 0026 Stage C
• Identity and SSO - MAS as the Matrix OIDC authority, Keycloak as the reference upstream IdP
• IdP Group Sync - one-way GitOps reconciler from Keycloak groups to managed Matrix room membership (ADR 0009)
• Model Provider Profiles - per-cluster model backends behind agentgateway (D16)
• Model Residency Matrix - prompt, jurisdiction, and credential boundaries for every shipped profile
• Sovereign Grounding Store - the composed CNPG + pgvector schema, ACL metadata, and exact-ranking contract (D18)
• Federation Spec - Matrix collaboration plane + A2A delegation plane across organizations (§8)
• Fediverse Interop Spec - ActivityPub as a second, additive cross-org transport with every M8 control mapped to an AP twin (M18)
• External-Network Interop - opt-in Slack/Telegram bridges as governed identity boundaries
• Slack Interop Walkthrough - enabling the opt-in mautrix-slack unit
• Observability Spec - metrics, traces, dashboards, and the LLM token-burn alert (§9)

Security

• Security Boundaries & Threat Model - trust zones and the controls that hold them (§7)
• Security and Auditor Dossier - evidence-bound OWASP Agentic and LLM Top 10 control mapping
• security/ - threat model, prompt-injection controls, supply-chain verification, OpenSSF self-assessment, external-audit readiness, and security release process

Federating with a partner organization

• Partner Federation Onboarding - bilateral checklist to federate with a partner org
• Partner Federation Offboarding - bilateral checklist to revoke a partner across every plane

Running your own copy

• Forking & Adapting - the checklist to run Fgentic under your own org, domain, GCP project, and registry
• Extending Without Forking - consume the signed standalone bridge chart and ship agents from your own repo as an out-of-tree pack
• Licensing & Foundation Strategy - Apache-2.0 rationale, AGPL boundaries, homeserver triggers (§10)

Contributing (humans and coding agents)

• Weekly This Week in Matrix Update - five-line artifact-led submission, Friday cadence, and publication evidence contract
• Agent Development Reference - detailed status, layout, runtime protocols, and conventions linked from the concise root agent instructions
• Hosted Coding Agents - configure Claude Code web and Codex Cloud sessions to work one pre-assigned issue end-to-end
• Documentation Site - generator decision, local authoring loop, and human-gated GitHub Pages publication
• Adopter Case Studies - published adopter evidence and the one-page contribution template

Architecture Decision Records

• adr/ - settled designs are revisited by proposing a new ADR, never a drive-by PR