Metadata-Version: 2.4
Name: fcc-agent-team-ext
Version: 1.9.0
Summary: FCC (Find → Create → Critique) Agent Team Framework
Author: INFORMATION COLLECTIVE, LLC
License-Expression: MIT
Project-URL: Repository, https://github.com/rollingthunderfourtytwo-afk/l2_fcc_agent_team_ext
Project-URL: Documentation, https://rollingthunderfourtytwo-afk.github.io/l2_fcc_agent_team_ext/
Project-URL: Changelog, https://github.com/rollingthunderfourtytwo-afk/l2_fcc_agent_team_ext/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/rollingthunderfourtytwo-afk/l2_fcc_agent_team_ext/issues
Keywords: fcc,agent,workflow,simulation,docs-as-code,personas,riscear,plugin,observability,collaboration,event-bus,dashboard,a2a,mcp,protocol,jv-governance,open-science,d3,websocket
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Typing :: Typed
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyyaml>=6.0
Requires-Dist: jsonschema>=4.23
Requires-Dist: click>=8.0
Requires-Dist: jinja2>=3.1
Requires-Dist: anthropic>=0.18.0
Requires-Dist: openai>=1.0.0
Requires-Dist: python-dotenv>=1.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: pytest-xdist>=3.5; extra == "dev"
Requires-Dist: pytest-timeout>=2.3; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Requires-Dist: numpy>=2.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs>=1.5; extra == "docs"
Requires-Dist: mkdocs-material>=9.4; extra == "docs"
Requires-Dist: mkdocs-material-extensions>=1.3; extra == "docs"
Requires-Dist: mkdocs-print-site-plugin>=2.4; extra == "docs"
Requires-Dist: mkdocs-static-i18n>=1.3; extra == "docs"
Requires-Dist: pymdown-extensions>=10.0; extra == "docs"
Provides-Extra: observability
Requires-Dist: opentelemetry-api>=1.20; extra == "observability"
Requires-Dist: opentelemetry-sdk>=1.20; extra == "observability"
Provides-Extra: otel
Requires-Dist: opentelemetry-api>=1.27.0; extra == "otel"
Requires-Dist: opentelemetry-sdk>=1.27.0; extra == "otel"
Requires-Dist: opentelemetry-exporter-otlp-proto-grpc>=1.27.0; extra == "otel"
Provides-Extra: notebooks
Requires-Dist: jupyter>=1.0; extra == "notebooks"
Requires-Dist: notebook>=7.0; extra == "notebooks"
Requires-Dist: ipykernel>=6.0; extra == "notebooks"
Requires-Dist: matplotlib>=3.7; extra == "notebooks"
Requires-Dist: pandas>=2.0; extra == "notebooks"
Requires-Dist: nbformat>=5.7; extra == "notebooks"
Provides-Extra: streamlit
Requires-Dist: streamlit>=1.30; extra == "streamlit"
Requires-Dist: plotly>=5.0; extra == "streamlit"
Provides-Extra: cto
Requires-Dist: cto>=6.0; extra == "cto"
Provides-Extra: protocols
Requires-Dist: websockets>=12.0; extra == "protocols"
Provides-Extra: a2a
Requires-Dist: google-adk>=0.1.0; extra == "a2a"
Provides-Extra: mcp
Requires-Dist: mcp>=1.0.0; extra == "mcp"
Provides-Extra: jv
Provides-Extra: frontend
Requires-Dist: websockets>=12.0; extra == "frontend"
Provides-Extra: search
Requires-Dist: sentence-transformers>=2.0; extra == "search"
Requires-Dist: numpy>=1.24; extra == "search"
Provides-Extra: knowledge
Requires-Dist: rdflib>=7.0; extra == "knowledge"
Provides-Extra: rag
Requires-Dist: sentence-transformers>=2.0; extra == "rag"
Requires-Dist: numpy>=1.24; extra == "rag"
Provides-Extra: ollama
Provides-Extra: litellm
Requires-Dist: litellm>=1.40; extra == "litellm"
Provides-Extra: collab-realtime
Requires-Dist: y-py>=0.6.0; extra == "collab-realtime"
Provides-Extra: deploy
Requires-Dist: pyyaml>=6.0; extra == "deploy"
Provides-Extra: full
Requires-Dist: opentelemetry-api>=1.27.0; extra == "full"
Requires-Dist: opentelemetry-sdk>=1.27.0; extra == "full"
Requires-Dist: opentelemetry-exporter-otlp-proto-grpc>=1.27.0; extra == "full"
Requires-Dist: jupyter>=1.0; extra == "full"
Requires-Dist: notebook>=7.0; extra == "full"
Requires-Dist: ipykernel>=6.0; extra == "full"
Requires-Dist: matplotlib>=3.7; extra == "full"
Requires-Dist: pandas>=2.0; extra == "full"
Requires-Dist: nbformat>=5.7; extra == "full"
Requires-Dist: streamlit>=1.30; extra == "full"
Requires-Dist: plotly>=5.0; extra == "full"
Requires-Dist: websockets>=12.0; extra == "full"
Requires-Dist: google-adk>=0.1.0; extra == "full"
Requires-Dist: mcp>=1.0.0; extra == "full"
Requires-Dist: sentence-transformers>=2.0; extra == "full"
Requires-Dist: numpy>=1.24; extra == "full"
Requires-Dist: rdflib>=7.0; extra == "full"
Requires-Dist: litellm>=1.40; extra == "full"
Dynamic: license-file

# FCC Agent Team Extension

<!-- status-badges-start (v1.9.0) -->
[![CI](https://img.shields.io/github/actions/workflow/status/rollingthunderfourtytwo-afk/l2_fcc_agent_team_ext/ci.yml?branch=main&label=CI)](https://github.com/rollingthunderfourtytwo-afk/l2_fcc_agent_team_ext/actions/workflows/ci.yml)
[![Coverage](https://img.shields.io/badge/coverage-99%25-brightgreen)](https://github.com/rollingthunderfourtytwo-afk/l2_fcc_agent_team_ext/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)](pyproject.toml)
[![Helm chart 0.8.0](https://img.shields.io/badge/helm-chart%200.8.0-0F1689)](charts/fcc/Chart.yaml)
[![Publications](https://img.shields.io/badge/publications-27%2B%20artifacts-purple)](publications/_output/)
[![Release](https://img.shields.io/badge/release-v1.9.0-blue)](https://github.com/rollingthunderfourtytwo-afk/l2_fcc_agent_team_ext/releases/tag/v1.9.0)
[![Code of Conduct](https://img.shields.io/badge/code%20of%20conduct-Contributor%20Covenant%202.1-ff69b4)](CODE_OF_CONDUCT.md)
<!-- status-badges-end -->

> **v1.9.0 SHIPPED (2026-06-18) — Phase 1: Ecosystem Forensics Consolidation, Registry Re-Sync & Standards Adoption.** A live 7-repo forensic sweep (NEXUS/RC, AOME, PAOM, CONSTEL, CTO, PHOENIX, AURORA) re-grounded FCC against ~3 weeks of undocumented ecosystem drift. No framework API changes — the surface is vendored-registry currency and ecosystem cohesion: re-vendored the NEXUS registries from RC v6.2.0 (constellation ports **8600→3900** per ADR-020, 22→**23 projects**), mirrored PAOM's `journey_event_v1` schema with a 12-test conformance contract, added the **registry-sync drift bot** (cohesion mechanism #3) + an **R-CPV reconciliation baseline**, declared the ecosystem standards FCC speaks (Web MCP `draft-2026-05-09`, A2A agent-card 0.3.0), and refreshed the ecosystem docs to the 2026-06-18 sister versions. It continues the **v1.8.3 → v2.0.0 ecosystem re-sync, full-parity UAT & persona-rationalization arc** — see [ROADMAP.md](ROADMAP.md) for the 5-phase plan and [CHANGELOG.md](CHANGELOG.md) for full release notes.

**FCC (Find → Create → Critique)** agent workflow framework — a clean, well-structured Python package for orchestrating documentation agent teams with plugin ecosystem, event bus, observability, and human-in-the-loop collaboration.

## Quick Start

### For Users

```bash
pip install fcc-agent-team-ext
fcc --version
```

### For Contributors

```bash
git clone https://github.com/rollingthunderfourtytwo-afk/l2_fcc_agent_team_ext.git
cd l2_fcc_agent_team_ext
make venv && source .venv/bin/activate
make install-dev
make test && make lint
```

## What is FCC?

FCC is a five-phase workflow for documentation creation:

1. **Find** — Research personas gather and synthesize information
2. **Create** — Design, operations, and user-facing personas produce artifacts
3. **Build** — Engineering personas construct implementations and pipelines
4. **Critique** — Review and governance personas ensure quality
5. **Ops** — Operational personas manage deployment and monitoring

**102 core personas** across 20 categories, **45 vertical personas** across 6 industry packs (healthcare, finance, legal, insurance, energy, government), and **23 plugin personas** — **147 total** — collaborate through message-passing workflows with feedback loops, event-driven messaging, observability tracing, human-in-the-loop collaboration, A2A/MCP protocol integration, and real-time web dashboards:

| Category | Count | Key Personas |
|----------|-------|----------|
| **Core** | 5 | Research Crafter, Blueprint Crafter, Documentation Evangelist, Runbook Crafter, User Guide Crafter |
| **Integration** | 8 | Catalog Indexer, UI Mockup, Semantic Taxonomy, Traceability, Blueprint Validator, Research Inventory, SAFe Metrics, Performance Tuner |
| **Governance** | 4 | Data Governance, Privacy Taxonomy, Governance Compliance Auditor, Key Vault Config Steward |
| **Stakeholder** | 5 | Collaboration Orchestrator, Executive Communicator, Roadmap Synchronizer, Content Publisher, Anti-fact Mitigation |
| **Champion** | 4 | Research Crafter Champion, Blueprint Crafter Champion, User Guide Champion, Doc Evangelist Champion |
| **Data Engineering** | 6 | SQL Query Crafter, Transformation Alchemist, Pipeline Orchestrator, Integration Specialist, Quality Guardian, Automation Scripter |
| **ML Lifecycle** | 9 | Data Sourcing, EDA Navigator, Feature Architect, Model Architect, Experiment Scientist, Inference Orchestrator, Insight Reporter, Interpretability Analyst, Model Ops Steward |
| **ML Models** | 11 | Neural Network, Logistic Regression, Gradient Boosted Trees, Random Forest, Isolation Forest, DBSCAN, Q-Learning, Siamese Neural Network, Clustering, Collaborative Filtering, Forecasting |
| **DevOps** | 3 | Pipeline Builder, DevOps Engineer, User Stories Specialist |
| **App Development** | 2 | App Maker, Notebook Collaboration Coach |
| **UX Visualization** | 6 | D3 Visualization Architect, Interactive Dashboard Designer, NanoCube Analyst, Real-time Event Renderer, Hypothesis Explorer, UX Accessibility Auditor |
| **Protocol Engineering** | 6 | A2A Skill Designer, MCP Tool Architect, Event Bridge Orchestrator, WebSocket Stream Manager, Protocol Compliance Auditor, AGENTS.md Generator |
| **JV Governance** | 6 | IP Evaluation Analyst, Partnership Coordinator, Patent Portfolio Assessor, Open Science Compliance Officer, JV Dependency Auditor, Innovation Registry Steward |
| **Specialized** | 27 | Open Science, Responsible AI, Privacy, Knowledge Graph, Local-First AI, JV Collaboration, Docs-as-Code personas |

Champions are elevated personas that orchestrate teams of base personas. Each persona supports **6 action types**: scaffold, refactor, debug, test, compare, document.

## Who Is This For?

- **Beginners / Students** — Learn agent orchestration patterns, persona-based workflows, and documentation-as-code methodologies through a well-structured, tested codebase with comprehensive examples. Start with *Understanding FCC* (Book 1).
- **Developers** — Build agent-powered documentation pipelines using a modular Python framework with CLI tooling, simulation engines, plugin system, event bus, semantic search, and RAG pipeline. Start with *Building with FCC* (Book 2).
- **Researchers** — Study the R.I.S.C.E.A.R. persona specification, 56-dimension persona profiling, Discernment Matrix, and Design Target Factors as formal models for human-AI collaboration. Use knowledge graphs and event replay for reproducible experiments. Start with *Advanced FCC* (Book 3).
- **Practitioners** — Deploy FCC workflows in enterprise settings with governance controls, quality gates, capability tagging, observability tracing, human-in-the-loop collaboration, federated knowledge graphs, and Scaled Agile alignment.

See [Learning Paths](docs/getting-started/learning-paths.md) for audience-specific guided routes through the framework.

## R.I.S.C.E.A.R. Framework

The full R.I.S.C.E.A.R. specification defines personas with 10 core components:

| Component | Purpose |
|-----------|---------|
| **R**ole | Identity and function |
| **I**nput | Data and background information |
| **S**tyle | Tone, language, and format |
| **C**onstraints | Limitations and requirements |
| **E**xpected Output | Desired structure and detail |
| **A**rchetype | Fundamental character/persona |
| **R**esponsibilities | Duties and ethical obligations |
| Role **S**kills | Skills for job execution |
| Role **C**ollaborators | Team collaboration patterns |
| Role **A**doption Checklist | Integration validation |

Plus: **Discernment Matrix** (6 traits), **Design Target Factors** (6 factors), and a **56-dimension Persona system** across 9 categories — all 102 personas fully populated with dimension profiles, discernment matrices, and design target factors.

## Key Concepts

- **FCC Cycle** — The five-phase workflow (Find → Create → Build → Critique → Ops) that structures how documentation is researched, produced, and reviewed. Artifacts flow forward through phases, with feedback edges enabling iterative refinement.
- **Personas** — AI agent roles defined by the R.I.S.C.E.A.R. specification. Each persona has a specific function, communication style, constraints, and collaboration patterns. 102 core personas span 20 categories, 45 vertical personas span 6 industry packs, plus 23 plugin personas (147 total).
- **Champions** — Elevated personas that orchestrate teams of base personas. Each champion coordinates 3-4 team members, enabling top-down coordination alongside bottom-up message passing.
- **Cross-Reference Matrix** — A queryable 100+ entry interaction map across 5 relationship types (handoff, feedback, coordination, governance, champion-of). Supports upstream, downstream, peer, and relationship-type queries.
- **Workflow Actions** — Six action types (scaffold, refactor, debug, test, compare, document) that personas can perform, with 312 action definitions across all personas. Executed via the ActionEngine.
- **Plugin System** — 10 plugin types (personas, engines, templates, scorers, validators, providers, governance, scenarios, workflows, subscribers) with entry-point discovery, dependency resolution, and cross-plugin orchestration.
- **Event Bus** — Thread-safe in-process pub/sub messaging with 81 event types, filtering, serialization, and deterministic replay.
- **Observability** — Structured tracing (FccTracer with @traced decorator) and metrics collection (FccMetrics), with console/JSON exporters and optional OpenTelemetry bridge.
- **Collaboration Engine** — Human-in-the-loop sessions with quality scoring, approval gates, handoff protocols, and progress tracking.
- **Scenarios** — Predefined test cases that exercise specific FCC workflows. 29 scenarios cover basic through advanced orchestration patterns.
- **Quality Gates** — Automated validation checkpoints that enforce documentation standards. 30+ gates with configurable severity (error, warning, info).
- **Protocol Bridge** — Cross-protocol event routing through EventBus, connecting A2A tasks, MCP tool calls, and WebSocket streams.
- **JV Governance** — Partnership evaluation framework with DualAxisEvaluator (5 technical + 5 strategic dimensions), IP reconciliation, and synergy assessment.
- **Open Science** — FAIR-compliant research support with 12 templates, 6 gates, and reproducibility workflows via OpenScienceRegistry.
- **WebSocket/SSE** — Real-time messaging protocols (WSProtocol with 9 message types, SSEStreamBridge) for EventBus-to-browser event streaming.

## Project Structure

```
src/fcc/
├── __init__.py          Package root, __version__
├── _resources.py        Centralized data/template path resolution (importlib.resources)
├── personas/            Persona models, R.I.S.C.E.A.R. specs, dimensions, registry, cross-reference
├── workflow/            Workflow graph models, traversal, actions, action engine
├── simulation/          Deterministic + AI-powered simulation engine
├── scenarios/           Scenario loading, dynamic validation framework
├── protocols/           A2A agent cards, MCP server, protocol bridge, WebSocket/SSE, stream manager
├── messaging/           Event bus, pub/sub, serialization, replay (81 event types)
├── observability/       Structured tracing, metrics collection, exporters
├── collaboration/       Human-in-the-loop sessions, scoring, progress tracking
├── dashboard/           Terminal-based ASCII dashboards (5 views)
├── scaffold/            CLI tool (20+ commands), template engine, doc generator, code analyzer
├── governance/          Capability tags, quality gates, constitutions, compliance, JV governance
├── plugins/             Plugin system (10 types), PAOM/AOME/CONSTEL plugins
├── ecosystem/           Cross-project ecosystem registry
├── artifacts/           SQLite artifact database, versioning
├── objectmodel/         Object model abstraction layer (Repository[T], Facade, Evolution, Federation)
├── search/              Semantic search (EmbeddingProvider, SearchIndex, PersonaSearchIndex)
├── knowledge/           Knowledge graphs (9 node types, 9 edge types, OWL/RDF/SKOS serializers, federation)
├── rag/                 RAG pipeline (DocumentChunker, SemanticRetriever, RAGPipeline)
├── federation/          Cross-project federation (EntityResolver, NamespaceRegistry, ChangeTracker)
├── evaluation/          CLEAR+ benchmarking, model cards, benchmark runner
├── compliance/          EU AI Act, NIST AI RMF, compliance pipeline, auditor
├── demos/               Guided demos (15 demos including evaluation and compliance)
├── tutorials/           Tutorial tracking (TutorialTracker, TutorialModule, progress checkpoints)
├── data/                Package data (included in wheel distribution)
│   ├── personas/        102 personas across 20 YAML files + cross-reference matrix + dimensions
│   ├── workflows/       7 workflow graphs (base, extended, complete, extended_84, 2 EAIFC)
│   ├── schemas/         31 JSON Schemas (persona, workflow, event, search, knowledge_graph, rag, federation, benchmark, model_card, compliance, ...)
│   ├── scenarios/       33 scenarios (6 starter + 11 advanced + 12 EAIFC + 4 evaluation/compliance)
│   ├── governance/      Tag registry (35+ tags) + quality gate definitions (30+ gates) + constitutions
│   ├── ecosystem/       Plugin dependencies, interactions
│   ├── objectmodel/     CTO patterns, evolution examples, best practices (educational YAML)
│   └── docs/            Topic registries, cookbooks, evolution guides, guidebook chapters, labs, assessments
└── templates/
    ├── project/         Jinja2 templates for project scaffolding
    └── docs/            23 Jinja2 templates for docs-as-code generation

notebooks/               23 Jupyter notebooks (beginner → expert)
apps/streamlit/          27 Streamlit apps (4 educational + 4 demo + 19 production)
frontend/                React 18 + D3.js web frontend (8 pages, 12 visualizations)
docs/guidebook/          24-chapter FCC Guidebook with labs and assessments
docs/books/              3-book series (30 chapters total)
docs/decisions/          5 Architecture Decision Records (ADRs)
tests/                   12,100+ tests across 230+ test files (100% coverage)
```

### v1.0.3 Highlights (Current)

- **27 Publication Artifacts Committed** — 4 books × 4 formats + executive/academic/reference cards (PDF, EPUB, DOCX, PPTX, HTML) in `publications/_output/`
- **Functional Publishing Pipeline** — `make pub-all` builds all 27 artifacts in ~3-5 min (Quarto 1.5 + Typst, no TeX needed)
- **Auto-Publish Workflow** — `.github/workflows/publish.yml` uploads artifacts to GitHub Releases on every release event
- **Complete `make help`** — All 44 targets documented (was 35 missing publishing section)
- **For-Teams Expansion** — 4 new files: workflow templates, multi-team governance, scaling guide, shared knowledge base
- **New Tutorials & Prompts** — building-your-own-book, contributing-to-books, team-coordination-prompts, publications-workflow-prompts

### v1.0.2 Highlights

- **300+ Mermaid Diagrams** — Comprehensive visual documentation across all personas, API modules, specifications, guidebook chapters, and book series
- **Multi-Format Publishing** — Quarto + Pandoc pipeline generating PDF books, EPUB, Word documents, PowerPoint decks, and reference cards
- **All 117 Personas in MkDocs** — Complete navigation coverage for all 102 core + 15 vertical personas across 23 categories (v1.2.0: extended to 147 personas with 6 vertical packs)
- **0 MkDocs Warnings** — All 299 strict-mode warnings resolved with automated link fixing and nav path correction
- **Executive Package** — Standalone PowerPoint deck and PDF for decision makers
- **Academic Package** — 12-week curriculum, workshop guide, and student workbook in PDF/DOCX
- **Quick-Start Reference Cards** — Condensed 1-2 page PDF cards for personas, CLI, workflows, and prompts
- **MkDocs Enhancements** — Version selector, print-site plugin, dark-mode Mermaid, code annotations, social cards

### v0.9.0 Highlights

- **CLEAR+ Benchmarks** — 7-dimension evaluation framework (Cost, Latency, Efficacy, Assurance, Reliability, Coverage, Explainability) with benchmark runner, regression detection, and CI advisory step
- **Model Cards** — 128 generated model cards (102 persona + 6 workflow + 20 category) in Mitchell/Gebru format (v1.2.0 regenerates to 173 cards: 147 persona + 6 workflow + 20 category)
- **EU AI Act Compliance** — 256+ codified requirements from Regulation 2024/1689 with risk classification for all personas
- **NIST AI RMF Mapping** — 29 subcategories with bidirectional crosswalk to EU AI Act
- **Compliance Pipeline** — Automated auditing with event emission (7 new EventTypes, 73 total)
- **15 Guided Demos** — including CLEAR benchmark, model card generation, AI Act audit, and compliance pipeline
- **27 Streamlit Apps** — including benchmark dashboard and compliance audit dashboard

### Architecture Overview

```mermaid
graph TB
    YAML[YAML Personas] --> REG[PersonaRegistry]
    REG --> SIM[Simulation Engine]
    REG --> DOC[Doc Generator]
    REG --> ACT[Action Engine]
    SIM --> TRACE[Traces]
    SIM --> BUS[Event Bus]
    DOC --> DOCS[6,500+ Doc Files]
    ACT --> BUS
    GOV[Governance] --> SIM
    BUS --> OBS[Observability]
    BUS --> COLLAB[Collaboration]
    CLI[fcc CLI] --> SIM
    CLI --> DOC
    CLI --> ACT
    CLI --> DASH[Dashboard]
    PLUG[Plugin System] --> REG
    PLUG --> ACT
    OBJ[Object Model] --> REG
    OBJ --> CTO_B[CTO Bridge]

    subgraph Protocol Layer
        A2A[A2A Agent Cards]
        MCP[MCP Server]
        AGENTS[AGENTS.md Gen]
        BRIDGE[Protocol Bridge]
    end

    REG --> A2A
    CLI --> MCP
    REG --> AGENTS
    BUS --> BRIDGE

    subgraph Web Layer
        REACT[React Frontend]
        WS[WebSocket]
        SSE_N[SSE]
    end

    BUS --> WS
    WS --> REACT
    BUS --> SSE_N

    subgraph JV Governance
        JV_REG[JV Registry]
        JV_EVAL[Dual-Axis Evaluator]
        OS[Open Science]
    end

    GOV --> JV_REG
    JV_REG --> JV_EVAL
    JV_REG --> OS
```

## Ecosystem Documentation

FCC is one project in a **22+ project ecosystem** — every sibling project carries a codename (PHOENIX, NEXUS, POLARIS, LYRA, AURORA, ATHENIUM, MNEMOSYNE, and the 10 constellation vocabulary packs), and each codename encodes a specific ecosystem role. The `docs/ecosystem/` tree is the single source of truth for what those codenames mean, how the projects coordinate, which services cross repo boundaries, and what license terms flow through the canonical seed-data pipeline. If you don't know what **PHOENIX** or **POLARIS** or **LYRA** is, start here.

- **[Ecosystem Overview](docs/ecosystem/README.md)** — landing page with audience-based quick nav (NEW in v1.6.1)
- **[Codename Decoder](docs/ecosystem/codename-decoder.md)** — codename → full name + origin reasoning + local clone path + GitHub URL for every ecosystem project
- **[Alignment Status](docs/ecosystem/alignment-status.md)** — 19-project registry, three-tier classification, ecosystem topology diagram
- **[Universal Services](docs/ecosystem/universal-services.md)** — 22-entry service-coordination superset (FCC ↔ sibling project contracts)
- **[Tri-Authority Topology](docs/ecosystem/tri-authority-topology.md)** — canonical hub-and-spoke view of FCC ↔ NEXUS ↔ PHOENIX ↔ ORCHESTRA coordination (NEW in v1.7.1)
- **[Coordination Records](docs/ecosystem/coordination/README.md)** — per-authority handoff playbooks (NEW in v1.7.1)
- **[NEXUS Research Coordination](docs/ecosystem/coordination/nexus-research-coordination.md)** — Research Center industry-paper + JV-statistics handoffs
- **[PHOENIX Open-Science Coordination](docs/ecosystem/coordination/phoenix-open-science-coordination.md)** — ai-coe-docs open-science + quality-gate + patent-IP coordination
- **[ORCHESTRA Integration-Tests Coordination](docs/ecosystem/coordination/orchestra-integration-tests-coordination.md)** — public cross-repo contract-test gate
- **[Seed-Canonical License Notices](docs/ecosystem/seed-canonical-license-notices.md)** — Pillar A canonical seed-data license terms (v1.6.0)
- **[RC Coordination Record](docs/ecosystem/rc-coordination-v143.md)** — Research Center handoff + statistics coordination
- **[ICE-EXT Patent Coordination](docs/ecosystem/ice-ext-patent-coordination-v143.md)** — patent-delegation coordination with ice_ext/POLARIS

For architectural + plugin-level protocol details (A2A agent cards, MCP servers, plugin matrix), keep reading the section below.

## Ecosystem & Protocol Integration

FCC operates within a 10+ project ecosystem. Six projects already implement A2A protocol and MCP servers:

| Project | A2A | MCP | FCC Plugin |
|---------|-----|-----|------------|
| **PAOM** | Agent Card | 25 tools | 13 personas |
| **AOME** | Agent Card builder | 9 tools + 5 resources | 5 personas |
| **CONSTEL** | Agent Card builder | Routes | 5 personas |
| **CTO** | Full protocol | Integrated server | Object model bridge |
| **Research Center** | Full (8 skills) | 4 tools | — |
| **Sky-Parlour** | Handlers | Extended client | — |
| **FCC** | Agent Card generation | 14 tools + 14 resources | Protocol bridge |

FCC's R.I.S.C.E.A.R. specification is a strict superset of A2A Agent Cards — any persona can be projected down to an Agent Card without loss. See [Protocol Architecture](docs/specification/protocol-architecture.md) and [Ecosystem Integration Guide](docs/developer/ecosystem-integration-guide.md) for details.

## Knowledge Federation

FCC v0.8.0 introduces a full knowledge layer for intelligent document and persona retrieval:

- **Semantic Search** (`fcc.search`) — Vector embedding-based search across personas, actions, and documents. Pluggable `EmbeddingProvider` protocol with mock (384d) and real backends. `PersonaSearchIndex` and `ActionSearchIndex` for domain-specific search.
- **Knowledge Graphs** (`fcc.knowledge`) — Graph representation of the entire FCC ecosystem with 9 node types (persona, workflow, action, category, dimension, plugin, event, scenario, gate) and 9 edge types. Export to OWL, RDF, SKOS, and JSON-LD. Federation support for cross-project graphs.
- **RAG Pipeline** (`fcc.rag`) — Retrieval-Augmented Generation pipeline with 6 chunking strategies, semantic retrieval, and persona-aware query augmentation. Enables intelligent Q&A over the 6,500+ document corpus.
- **Federation** (`fcc.federation`) — Cross-project entity resolution, namespace registry (11 ecosystems), change tracking, and federated knowledge graph merging.

## Patent

> **DRAFT — not legal advice. For counsel review only.** Nothing under `docs/patent/` constitutes legal advice or a filing decision.

FCC was designated the patent-centric anchor of the ecosystem at v1.3.9. The full draft patent package lives under [`docs/patent/`](docs/patent/README.md) — 12 files covering an invention disclosure form, prior-art landscape (35 items reviewed, 0 direct overlaps, 2 Medium-risk, 8 Low-risk flagged), a **provisional specification with 20 claims** (3 independent + 17 dependent), a **non-provisional utility specification with 32 claims** (5 independent + 27 dependent), a per-claim freedom-to-operate risk register, and a drawings pointer re-using the v1.3.7 4+1 UML views as FIG. 1–6. The package was **FTO-clean** per the v1.3.9 audit and remains **counsel-gated** — actual filing is explicitly out of scope until patent counsel is engaged. Ownership: INFORMATION COLLECTIVE, LLC; operational owner = Innovation Handoff Liaison (IHL) persona.

The [`make pub-patent`](Makefile) target (v1.5.4+: direct Pandoc + typst PDF engine; previously a Quarto profile that required LaTeX) regenerates DRAFT PDF + DOCX with `DRAFT — COUNSEL REVIEW ONLY — NOT FOR FILING` subtitle + posture. Artifacts land at `publications/_output/patent/fcc-patent-package-draft.{pdf,docx}` and are preserved in the repository for counsel-review convenience.

**Release-asset disclaimer:** patent artifacts under `publications/_output/patent/**` are **NOT shipped in GitHub Release assets**. The release workflow's asset whitelist excludes `patent/**` explicitly — the DRAFT watermark and counsel gate keep them out of any public distribution channel until counsel signs off.

Cross-repo consolidation to **ai-coe-docs (PHOENIX)** as the ecosystem single-source-of-truth, any public filing, and the FCC → ai-coe-docs mirror PR all remain **owner-approval-gated** per the v1.4.3 delegation runbook and the post-v1.5.0 cuddly-turtle plan.

## Book Series

Three comprehensive books in `docs/books/` covering all aspects of the FCC framework:

| Book | Chapters | Audience |
|------|----------|----------|
| **Understanding FCC** | 10 | Beginners, students, managers |
| **Building with FCC** | 10 | Developers, integrators |
| **Advanced FCC** | 10 | Researchers, architects, contributors |

Each book includes worked examples, exercises, and cross-references to the guidebook labs.

## Publications (Multi-Format Downloads)

All documentation is available as pre-built downloadable artifacts in [`publications/_output/`](publications/_output/) and attached to [GitHub Releases](https://github.com/rollingthunderfourtytwo-afk/l2_fcc_agent_team_ext/releases). Formats: **PDF · EPUB · DOCX · HTML · PPTX**.

### Books (PDF, EPUB, DOCX, HTML)

| Book | PDF | EPUB | DOCX | HTML |
|------|-----|------|------|------|
| **Book 1: Understanding FCC** (10 ch) | [📄](publications/_output/books/book1-understanding-fcc.pdf) | [📖](publications/_output/books/book1-understanding-fcc.epub) | [📝](publications/_output/books/book1-understanding-fcc.docx) | [🌐](publications/_output/books/book1-understanding-fcc.html) |
| **Book 2: Building with FCC** (10 ch) | [📄](publications/_output/books/book2-building-with-fcc.pdf) | [📖](publications/_output/books/book2-building-with-fcc.epub) | [📝](publications/_output/books/book2-building-with-fcc.docx) | [🌐](publications/_output/books/book2-building-with-fcc.html) |
| **Book 3: Advanced FCC** (10 ch) | [📄](publications/_output/books/book3-advanced-fcc.pdf) | [📖](publications/_output/books/book3-advanced-fcc.epub) | [📝](publications/_output/books/book3-advanced-fcc.docx) | [🌐](publications/_output/books/book3-advanced-fcc.html) |
| **FCC Guidebook** (24 chapters) | [📄](publications/_output/books/fcc-guidebook.pdf) | [📖](publications/_output/books/fcc-guidebook.epub) | [📝](publications/_output/books/fcc-guidebook.docx) | [🌐](publications/_output/books/fcc-guidebook.html) |

### Executive Package (Decision Makers)
- **Executive Summary** — [PDF](publications/_output/executive/fcc-executive-summary.pdf) · [DOCX](publications/_output/executive/fcc-executive-summary.docx)
- **Executive Presentation** (10 slides) — [PPTX](publications/_output/presentations/fcc-executive-overview.pptx) · [HTML reveal.js](publications/_output/presentations/fcc-executive-overview.html)

### Academic Package (Educators)
- **12-Week Curriculum + Workshop + Workbook** — [PDF](publications/_output/academic/fcc-academic-edition.pdf) · [EPUB](publications/_output/academic/fcc-academic-edition.epub)

### Quick-Start Reference Cards (PDF, 1–2 pages each)
- [Persona Categories](publications/_output/reference-cards/persona-categories.pdf) — All 26 categories (20 core + 6 vertical), 147 personas
- [CLI Commands](publications/_output/reference-cards/cli-commands.pdf) — All fcc commands
- [Workflow Patterns](publications/_output/reference-cards/workflow-patterns.pdf) — 7 graph variants
- [Prompt Templates](publications/_output/reference-cards/prompt-templates.pdf) — 10 essential patterns
- [R.I.S.C.E.A.R. Quick Reference](publications/_output/reference-cards/riscear-quick-ref.pdf) — 10-component specification

**Build from source:** `make pub-all` (requires [Quarto 1.5+](https://quarto.org/docs/get-started/)). See [docs/publications/](docs/publications/index.md) for the build guide.

## Learning Paths

| If you are... | Start with... | Time |
|--------------|--------------|------|
| Student / beginner | [Beginner Path](docs/getting-started/learning-paths.md#beginner-path) | 1-2 hours |
| Software developer | [Developer Path](docs/getting-started/learning-paths.md#developer-path) | 4-8 hours |
| AI researcher | [Researcher Path](docs/getting-started/learning-paths.md#researcher-path) | 8-16 hours |
| Team lead / manager | [Practitioner Path](docs/getting-started/learning-paths.md#practitioner-path) | 16+ hours |
| PhD / academic | [Scientist Path](docs/getting-started/learning-paths.md#scientist-path) | Ongoing |

## CLI

```bash
# Project management
fcc init --name "my-project" --dir ./my-project          # Bootstrap FCC project
fcc add-persona "Custom Analyst" --phase Find --id CA    # Add persona
fcc validate                                              # Check project structure

# Simulation
fcc simulate --scenario GEN-001                           # Run simulation

# Documentation generation
fcc generate-docs --dir ./docs --personas all             # Generate all 6,500+ doc files
fcc generate-docs --dir ./docs --personas core            # Generate core persona docs only
fcc validate-docs --dir ./docs                            # Validate generated docs
fcc sitemap --dir ./docs                                  # Generate SITEMAP.md

# Plugins
fcc plugins list                                          # List installed plugins
fcc plugins info paom                                     # Show plugin details
fcc plugins validate                                      # Validate plugin compatibility

# Workflow actions
fcc action list                                           # List available actions
fcc action run scaffold --persona RC                      # Run scaffold action for RC

# Collaboration
fcc collab start --workflow base_sequence --participants "RC,BC,human1"
fcc collab turn --session <id> --content "Review findings"
fcc collab gate --session <id>                            # Evaluate approval gate
fcc collab status --session <id>                          # Check session status

# Dashboards
fcc dashboard ecosystem                                   # Project ecosystem overview
fcc dashboard personas                                    # Persona catalog
fcc dashboard quality                                     # Quality gate status
fcc dashboard collab                                      # Collaboration sessions

# Protocol integration
fcc protocol mcp-server                                      # Start MCP server
fcc protocol a2a-cards                                       # Generate A2A Agent Cards
fcc protocol agents-md                                       # Generate AGENTS.md
fcc protocol a2a-server                                      # Start A2A server

# Evaluation & compliance
fcc benchmark run --suite baseline --mock                    # Run CLEAR+ benchmarks
fcc benchmark compare baseline candidate                     # Compare benchmark runs
fcc model-card generate --all --output docs/model-cards      # Generate 173 model cards
fcc compliance-audit --regulation EU_AI_ACT                  # Run EU AI Act audit
fcc compliance-report --output compliance_report.md          # Generate compliance report
```

## Phase Roadmap

| Phase | Status | Tests | Description |
|-------|--------|-------|-------------|
| 1. Foundation | Done | 3 | Project skeleton, packaging, smoke tests |
| 2. Core FCC | Done | 43 | Personas, workflow graph, registry |
| 3. Simulation | Done | 32 | Engine, traces, AI client, scenarios |
| 4. Scaffolding CLI | Done | 22 | `fcc init`, templates, project config |
| 5. Governance | Done | 21 | Tags, quality gates, compliance |
| R.I.S.C.E.A.R. Expansion | Done | 259 total | Full 10-component spec, dimensions, strategic architecture |
| Extended Persona Gallery | Done | 693 total | 24 personas, cross-reference matrix, champion architecture, docs-as-code (1,348 files), dynamic validation |
| CI/CD, Scenarios & Docs | Done | 726 total | GitHub Actions CI/CD, MkDocs deployment, 11 advanced scenarios, 5 new validation rules |
| Coverage Push to 100% | Done | 757 total | 100% line coverage across 20 test files |
| Phase 5.5: Profiles & Docs UX | Done | 877+ total | 24 dimension profiles, documentation overhaul, MkDocs UX, 50 hand-written pages |
| Phase 6: Cross-Reference Expansion | Done | 1030+ total | Cross-reference matrix 16→106 entries, governance/champion-of types, 3 quality gates |
| Phase 7: Distribution | Done | 1168 total | PyPI packaging, release automation, `_resources` module |
| Phase 8: Plugin System & Ecosystem | Done | 1454+ total | 9 plugin types, 50→84 personas (17 categories), 5-phase workflow, artifact DB, ecosystem registry |
| Phase 9: EAIFC Integration | Done | 1705 total | 34 new personas, 6-action workflow (204 actions), ActionEngine, ConstitutionRegistry |
| Phase 10: Plugin Ecosystem & Collaboration | Done | 2472 total | Event bus, observability, collaboration engine, 10th plugin type, PAOM/AOME/CONSTEL plugins, dashboards |
| Phase 11: FCC Book, Notebooks & Streamlit | Done | 2932 total | Object model abstraction, CTO bridge, 12 notebooks, 10 Streamlit apps, 14-chapter guidebook |
| Phase 12: Protocol Integration & Web Frontend | Done | 5570+ total | A2A protocol, MCP server, 18 new personas (102 total), React frontend, JV governance, simulation hardening |
| Phase 13: Knowledge Federation & Doc Intelligence | Done | 9265 total | Semantic search, knowledge graphs, RAG pipeline, federation, demos, tutorials, 3 books, docs-from-code |
| Phase 14: Evaluation, Governance & Compliance | Done | 11,025+ total | CLEAR+ benchmarks, 128 model cards, EU AI Act compliance, NIST AI RMF, compliance pipeline, 73 event types |
| Phase 15 Stage I: Unified Object Model | Done | 11,439+ total | AOME/CONSTEL bridges, UnifiedModelFacade, 67 CTO↔AOME + 45 SID↔CTO mappings, unified search/KG/RAG, provider registry |
| Phase 15 Stage II: Enhanced Demos, UI & Messaging | Done | 11,892+ total | 4 new demos (19 total), PriorityEventBus, DLQ, circuit breaker, 81 EventTypes, 4 Streamlit apps (27 total) |
| Phase 15 Stage III: Documentation Excellence | Done | 12,052+ total | 6 book chapters (30 total), 4 notebooks (23 total), 4 guidebook chapters (24 total), maturity model |
| Phase 15 Stage IV: Platform Release & v1.0.0 | Done | 12,100+ total | VS Code extension, 3 domain verticals (15 new personas), public API freeze, migration guide, v1.0.0 release |
| v1.0.1: Documentation Overhaul | Done | 12,100+ total | Docs accuracy across 60+ files, guidebook restructure, model card version fix, adoption guide, audience quick-starts, expanded vertical prompts |
| v1.0.2: Multi-Format Publishing | Done | 12,100+ total | 300+ Mermaid diagrams, Quarto/Pandoc publishing pipeline, PDF/EPUB/DOCX/PPTX output, all 117 personas in MkDocs, 0 strict-mode warnings, executive/academic/reference packages |
| v1.0.3: Publishing Pipeline Live | Done | 12,100+ total | 27 artifacts built and committed, GitHub Actions publish workflow, make help completeness, for-teams expansion (5 files), 2 new tutorials, 2 new sample prompt files, README Publications section |
| **v1.1.0: Docker + AI Provider Expansion** | **Done** | **12,100+ total** | **4 Dockerfiles + compose stack, `make docker-*` targets, WebSocket bridge entry function with HTTP /health endpoint, Ollama plugin, LiteLLM plugin (100+ backends via one client), conservative auto-detection, scenario `ai_config` override, model-reference sweep, `[full]` optional deps group, deployment + provider docs (7 files), notebook 24, audience tutorials** |
| **v1.1.0.1: Forward-fix patch** | **Done** | **12,100+ total** | **4 forward-fix commits consolidated: frontend Dockerfile tsc bypass, backend image OOM fix (slim deps), WS bridge `/health` endpoint using proper `Response` object, Jupyter `HOME=/app` fix, `mkdocs-print-site-plugin` added to `[docs]`, `docs.yml` broken cross-repo links, `publish.yml` `apt-get install pandoc`. End-to-end local Docker stack verified: all 4 containers report healthy** |
| **v1.1.1: Helm + ghcr.io + vLLM** | **Done** | **12,100+ total** | **Multi-arch image push to `ghcr.io/rollingthunderfourtytwo-afk/fcc-*` (amd64+arm64), Helm chart at `charts/fcc/` (12 default + 14 prod K8s resources, 39 helm tests), helm-mirror CI for sister `fcc-helm` repo (inert until configured), kind k8s-smoke CI workflow, vLLM provider plugin (#7) with `docker/vllm.yml` GPU example + 17 tests, 7 deferred deployment docs (kubernetes/helm/security/observability/upgrade/images/helm-repo-mirror), `docs/providers/vllm.md`, notebook 25** |
| **v1.2.0: Vertical Schema Extension + Industry Packs** | **Done** | **12,100+ total** | **Schema v2 with nested R.I.S.C.E.A.R. + backward-compat v1 loader (`anyOf`), retrofitted healthcare/finance/legal (15 personas → rich content), 3 net-new packs (insurance 6, energy 6, government 6), healthcare+finance expansions (+12 medical/financial personas), 45 vertical personas total across 6 packs (up from 15 across 3), 5 research notes with standards sources, vertical risk profiles for EU AI Act, persona ID collision prevention script, cross-reference generator, 173 model cards regenerated, 20 audience tutorials, notebooks 26+27, vertical_explorer Streamlit app, guidebook ch25, book 3 ch11** |
| **v1.2.1: K8s Smoke + Vocabulary Plugins + Demo Expansion** | **Done** | **12,500+ total** | **Helm chart bumped to 0.2.0/appVersion 1.2.1, K8s smoke probe tuning + post-failure diagnostics, coverage ratchet start (94%), VocabularyProviderPlugin ABC + loader + athenium/mnemosyne plugins, 4 new subsystem notebooks (28-31) + full_stack demo + notebook 32, 16 audience subsystem tutorials, persona/archetype interaction atlas auto-generator** |
| **v1.2.2–v1.2.6: Coverage Ratchet** | **Done** | **13,000+ total** | **525 new coverage tests across 25 test files. Gate ratcheted: 94→95→96→97→98→98%. Targets: ai_client, action_engine, auditor, pipeline, runner, embeddings, requirements, feedback, dashboard, RAG, knowledge, federation, code_analyzer, observability, distiller, objectmodel, artifacts, plugins, demos, scaffold/cli (121 CliRunner tests)** |
| **v1.3.0: 10 External Project Scaffolds + Federation Expansion** | **Done** | **13,000+ total** | **10 constellation-codename projects (5 ontology + 5 metadata) scaffolded at `/mnt/d/.../Ideate/{codename}_ext/` with full CTO/CONSTEL-pattern applications (FastAPI + CLI + persistence + ETL + seed data + tests). Federation namespace registry 11→21, vocabulary mappings 95→175, vocabulary provider plugins 2→12. `fcc scaffold-vertical-project` CLI command. Coverage gate 98→99% with ABC/Protocol ellipsis exclusion + advisory `--cov-branch` CI job** |
| **v1.3.1: Foundation — Branch Gate + Seed-Full + Stale Doc Refresh** | **Done** | **13,000+ total** | **Hard `--cov-branch` gate (was advisory in v1.3.0); `make seed-full` implementation with pattern-based 500-1000 entity expansion; STRATEGIC_ARCHITECTURE_REVIEW.md refreshed v0.8.0→v1.3.1; ROADMAP.md rewritten (Phase 16+ → v1.3.x plan); docs/roadmap/release-plan.md refreshed v1.0.3→v1.3.1 with 11 new release entries** |
| **v1.3.2: Publication Pipeline — Mermaid Rendering + Markdown Format** | **Done** | **13,000+ total** | **`publications/scripts/render_mermaid.py` renders 280 mermaid diagrams across 228 files to SVG + PNG (560 assets committed); Pandoc Lua filter safety net (`mermaid-filter.lua`); all 27 existing artifacts rebuild with **embedded images** (PDF→SVG via Typst, DOCX→PNG, EPUB/HTML→SVG); **NEW Markdown publication format** — consolidated (single file per book) + per-chapter variants with dual representation (fenced source + image refs); Makefile targets `pub-diagrams`, `pub-markdown`, `pub-diagrams-clean`; CI `publications-check` advisory job** |
| **v1.3.3: Content Expansion — Sample Prompts + Persona Evolution + Audience Docs** | **Done** | **13,000+ total** | **11 new sample prompt files (vertical insurance/energy/government + evaluation/compliance/docker/federation/scaffold + beginner/educator/research) → 35 total; persona evolution content: `evolution-pathways.md` + 6 archetype deep-dives (shepherd/quant/investigator/architect/storyteller/safety-engineer) + persona-evolution-workshop; guidebook chapter 26 (25→26); notebook 33 persona evolution explorer (32→33); 8 new audience docs (beginner first-30-min + common-mistakes, scientist experimental-design + statistical-analysis, educator grading-rubrics + lab-exercise-bank, professional cost-analysis + security-review); mkdocs.yml nav expanded ~29 entries** |

## What's Next

**v1.3.5.2 released (2026-04-13)** — Third patch. Closes v1.3.5.1 deferred
items and ships a broad content expansion: 5 demo addenda
(`*-v1352-addendum.md` under `docs/tutorials/demos/`) covering WebSocket
stress-test, distiller vocabulary evolution, cross-project FAIR audit,
Sky-Parlour Phase-17 integration, full-stack OpenTelemetry trace; 10 new
sample-prompt files (architecture teaching, persona evolution stages,
plugin-dev gap-fill, guided-demo follow-ups); a first-class ecosystem
alignment status table covering all 10 sibling projects; light-touch
figure prose across 111 MkDocs-only Mermaid blocks. A new v1352 Showcase
demo walks the 5 addendum flows end-to-end (built-in demo count: 20 → 21).

**v1.3.5.1 released (2026-04-13)** — Second patch of the v1.3.5.x series. Ships
a brand-new `docs/architecture/` tree: 5 classDiagrams, 6 sequenceDiagrams, 4
data-flow diagrams, 4 use-case diagrams (one per audience tier), a repo site
map, an API-boundary matrix covering all 6 external interfaces, a plugin-
boundary reference for all 11 plugin types, and a side-by-side "federated vs
individual" comparison for both the object model and the knowledge graph. The
5 ADRs under `docs/decisions/` are finally in the mkdocs nav (Reference →
Architecture Decisions). Each audience tier has a new "See also" block bridging
to the others and to the relevant architecture slice. Also: `render_mermaid.py`
now disambiguates slugs by parent directory so the 20 `overview.md` siblings
no longer collide on asset filenames (302 renders → 302 distinct PNG/SVG
files, up from 281). Build-time guard in `build_all.sh` drops the redundant
pre-render pass, saving ~10 minutes on WSL2.

**v1.3.5 released (2026-04-13)** — First patch. Main CI unblocked; publication
pipeline fixed so DOCX/EPUB embed real PNG diagrams instead of blank boxes;
56 figures in publication source trees authored with unified "Figure N"
captions + intros + followups; Quarto LOF/LOT enabled across PDF/DOCX/EPUB/HTML.

**v1.4.0 released (2026-04-22)** — **Ecosystem pivot pillar 1 COMPLETE.**
Published all 10 constellation vertical projects as independent public
GitHub repositories with their own release cycles, ending the
pre-v1.4.0 prework pipeline (8 releases shipped in this session):

- **Medical** — [ophiuchus_ext](https://github.com/rollingthunderfourtytwo-afk/ophiuchus_ext) (HL7 FHIR Genomics + DICOM + IEC 62304) · [serpens_ext](https://github.com/rollingthunderfourtytwo-afk/serpens_ext) (ICH E2B + EudraVigilance)
- **Financial** — [libra_ext](https://github.com/rollingthunderfourtytwo-afk/libra_ext) (FIBO, EDM Council) · [crater_ext](https://github.com/rollingthunderfourtytwo-afk/crater_ext) (ISO 20022 + BCBS 239)
- **Insurance** — [scutum_ext](https://github.com/rollingthunderfourtytwo-afk/scutum_ext) (ACORD v2.11) · [norma_ext](https://github.com/rollingthunderfourtytwo-afk/norma_ext) (Solvency II + IFRS 17)
- **Energy** — [pyxis_ext](https://github.com/rollingthunderfourtytwo-afk/pyxis_ext) (IEC 61970 CIM) · [vela_ext](https://github.com/rollingthunderfourtytwo-afk/vela_ext) (IEC 62325 + CGMES + IEEE 1547)
- **Government** — [columba_ext](https://github.com/rollingthunderfourtytwo-afk/columba_ext) (DCAT-US 3.0) · [caelum_ext](https://github.com/rollingthunderfourtytwo-afk/caelum_ext) (NIEM 6.0 + eIDAS 2.0)

Each repo is `v0.2.0` signaling FCC v1.4.0 alignment; each carries the
full public-release package from v1.3.11 (CODE_OF_CONDUCT, CONTRIBUTING,
SECURITY, MIT LICENSE, CI/release workflows, issue + PR templates,
release-checklist runbook). Helm chart bumped to `0.3.0`. Pillars 2-5
(GraphRAG, real canonical seed data, i18n, real-time multi-user
collaboration, advanced federation, performance optimization) defer
to v1.4.1+.

**v1.3.11 released (2026-04-22)** — Seventh and final patch of the
pre-v1.4.0 prework plan. Wires `ecosystem-integration-tests` 49
offline contract tests as an advisory CI gate. Extends the vertical-
project scaffold with a `--public-release` flag emitting all 10
artifacts a constellation needs to stand up as an independent
GitHub repo (CODE_OF_CONDUCT, CONTRIBUTING, SECURITY, LICENSE,
CI/release workflows, issue + PR templates, release-checklist
runbook). Dry-runs all 10 constellation tarballs via
`make pub-constellations`. Bumps all 12 vocabulary_provider plugins
to version 0.2.0 with FCC pin `>=1.3.11`. +19 new tests.

**Pre-v1.4.0 plan COMPLETE** (7 of 7 patches shipped in this
session — v1.3.5.4 through v1.3.11).

**Next: v1.4.0 final** — publish the 10 constellation GitHub repos
(Ophiuchus, Serpens, Libra, Crater, Scutum, Norma, Pyxis, Vela,
Columba, Caelum). This is a hard-to-reverse public action:
`gh repo create` for each, push release tarballs, enable Actions
+ Issues + Discussions. **Requires explicit user approval before
proceeding.**

**v1.3.10 released (2026-04-22)** — Sixth patch of the pre-v1.4.0
prework plan. Ships the full 9-audience canonical taxonomy the
ecosystem has standardized on (beginners, developers, educators,
scientists, architects, operators, auditors, knowledge-engineers,
data-architects) — 25 new audience pages (~29,000 words), 4 new
guidebook chapters (ch27-30) with 13 new diagrams, 5 new sample
prompts (45 → 50), 5 new Jupyter notebooks (33 → 38), and a
cross-link matrix connecting every audience to its related
resources. Gracefully deprecates `for-professionals/` +
`for-teams/` with MIGRATION.md stubs + banners; content preserved
for external-link stability. Navigation reorganized across
`mkdocs.yml` into canonical order; `publications/_quarto.yml` now
carries 8 parts. No source changes; test suite + persona count
unchanged.

**Next: v1.3.11 — ecosystem-integration-tests CI gate +
constellation scaffold for public release + v1.4.0-rc cut.** Adds
`make ecosystem-check` that runs the 49 offline contract tests
from `ecosystem-integration-tests`, updates all 12 vocabulary
provider plugins to match PAOM v3.2.0, and cuts the v1.4.0 release
candidate.

**v1.3.9 released (2026-04-22)** — Fifth patch of the pre-v1.4.0
prework plan. FCC was designated patent-centric; this release ships
the full draft patent package READY FOR COUNSEL REVIEW. Full
`docs/patent/` tree (12 files, 40,570 words): invention disclosure
form, prior-art landscape (35 items reviewed — 0 direct overlaps,
2 Medium-risk items noted, 8 Low-risk), provisional specification
with abstract + 20 claims (3 independent + 17 dependent), utility
specification with 32 claims (5 independent + 27 dependent), FTO
analysis + per-claim risk register, drawings pointer (4+1 UML from
v1.3.7 re-used as FIG. 1-6). IP Evaluation Analyst introduced as
the 104th core persona (governance 5 → 6). Quarto `make pub-patent`
target builds the patent PDF + DOCX with DRAFT watermark. PAOM v1.4
preview plugin surface declared at `fcc.plugins.v1_4_preview.*`
with 6-month deprecation policy. +6 new PAOM compat tests. Filing
requires patent counsel engagement; outside plan scope.

**Next: v1.3.10 — 9-audience documentation scale-up.** FCC currently
has 5 audience dirs (`for-beginners`, `for-educators`, `for-scientists`,
`for-professionals`, `for-teams`); the ecosystem has standardized on 9
canonical audiences. v1.3.10 adds `for-developers`, `for-architects`,
`for-operators`, `for-auditors`, `for-knowledge-engineers`, and
`for-data-architects` with 20+ sample prompts, 10+ new Jupyter
notebooks, and guidebook chapters 27-30.

**Pre-v1.4.0 plan (7 patches total):**

- **v1.3.5.4** — Inventory + port realignment + carry-overs + JV L2 unblock (shipped 2026-04-22)
- **v1.3.6** — Self-audit + `fcc admin` CLI + PlantUML pipeline + forensic auditor archetype (shipped 2026-04-22)
- **v1.3.7** — 4+1 UML views + C4 context diagram + React `/admin` route + StressTestPanel.tsx (shipped 2026-04-22)
- **v1.3.8** — 58-gate quality registry from PHOENIX + R.I.S.C.E.A.R. completeness + 12 open-science templates (shipped 2026-04-22)
- **v1.3.9** — Patent infrastructure (provisional + utility + FTO) + PAOM v1.4-preview plugin surface (shipped 2026-04-22)
- **v1.3.10** — 9-audience documentation scale-up (6 new audience dirs, 25 pages, 4 guidebook chapters, cross-link matrix) (shipped 2026-04-22)
- **v1.3.11** — Ecosystem-integration-tests CI gate + constellation public-release scaffold + 12 plugin bumps + dry-run tarballs (shipped 2026-04-22)
- **v1.4.0** — Ecosystem pivot pillar 1: 10 constellation repos published to GitHub as independent public releases (this release; pillars 2-5 defer to v1.4.1+)

**Past releases:**

- **v1.1.0** — Docker + Compose stack, 6 AI providers
- **v1.1.0.1** — Forward-fix patch
- **v1.1.1** — Helm chart, multi-arch ghcr.io, vLLM provider
- **v1.2.0** — Vertical schema extension + 6 industry packs (45 personas)
- **v1.2.1** — K8s smoke + vocabulary plugins + demo expansion
- **v1.2.2–v1.2.6** — Coverage ratchet (94% → 98%)
- **v1.3.0** — 10 external project scaffolds + federation 11→21 + coverage to 99%
- **v1.3.1** — Hard branch gate + seed-full + stale doc refresh
- **v1.3.2** — Publication pipeline: mermaid rendering + Markdown format
- **v1.3.3** — Content expansion: sample prompts, persona evolution, audience docs
- **v1.3.4** — Hotfix: green CI + restored publications pipeline
- **v1.3.5** — Publication pipeline quality + figure numbering + main CI unblock
- **v1.3.5.1** — New architecture/UML docs tree (24 docs) + slug-collision fix + build-perf guard
- **v1.3.5.2** — Full republish + 5 demo addenda + 10 sample prompts + ecosystem alignment + 111 light-touch figure annotations
- **v1.3.5.3** — Coverage gate restored 98→99 + needs_render guard bug fixed; closes v1.3.5.x series
- **v1.3.5.4** — Inventory + port realignment (10 → 19 projects, constellation ports 8300→8600) + vendored RC registries with CI drift test + carry-overs resolved
- **v1.3.6** — Self-audit + admin CLIs + PlantUML pipeline + Forensic Auditor persona (103rd; governance 4→5)
- **v1.3.7** — 4+1 UML views + C4 context diagram + REST admin API + React /admin route + StressTestPanel.tsx
- **v1.3.8** — 58-gate quality registry from PHOENIX + R.I.S.C.E.A.R. strict gate + 12 OPEN-SCI templates + 3 PHOENIX Tier-1 gap closures
- **v1.3.9** — Patent infrastructure (12 files, 40,570 words, 20 provisional + 32 utility claims) + IP Evaluation Analyst (104th persona) + PAOM v1.4-preview (this release)

## Cross-Project Vocabulary Contracts (new in v1.2.1)

FCC owns YAML vocabulary mapping files at `src/fcc/data/objectmodel/{namespace}_vocabulary_mappings.yaml` that describe how dataclass shapes from sister projects (Athenium, Mnemosyne, AOME, CTO, Distiller, Sky-Parlour, ...) align with FCC concepts. v1.2.1 added the **`VocabularyProviderPlugin`** ABC and **`VocabularyMappingLoader`** so these contracts can be verified at runtime:

```python
from fcc.objectmodel.vocabulary_loader import VocabularyMappingLoader
from fcc_athenium_plugin import AtheniumVocabularyProvider

loader = VocabularyMappingLoader()
store = loader.from_data_dir()  # Loads 175 mappings from 20 YAML files (v1.3.0)
result = loader.verify_against_plugin(store, AtheniumVocabularyProvider())
print(result)  # → "athenium: clean (8/8 mappings verified)"
```

The pattern is one-directional: FCC owns the mapping files (they describe the FCC target side of every cross-vocabulary relationship), sister projects own the source dataclass shapes, and the plugin packages (`plugins/fcc-{codename}-plugin/`) are thin adapters shipped by FCC. Sister projects remain pure-data dataclass libraries with no FCC dep. v1.3.0 expanded from 2 to **12 vocabulary provider plugins** covering 20 namespaces and 175 mappings.

See `src/fcc/plugins/base.py:VocabularyProviderPlugin`, `src/fcc/objectmodel/vocabulary_loader.py`, and `tests/integration/test_{codename}_vocabulary.py` for the contract definition, loader, and integration tests.

See [ROADMAP.md](ROADMAP.md) for details.

## Documentation Site

The FCC documentation site is built with MkDocs Material and offers 8 audience-targeted navigation paths:

| Audience | Entry Point |
|----------|-------------|
| Beginners / Students | Getting Started → Tutorials |
| Developers | Developer Guide |
| Researchers | Specification |
| Practitioners | Tutorials → Customization |
| Decision Makers | For Decision Makers |
| Managers / Team Leads | For Teams |
| Content Strategists | Personas → Specification |
| Open Source Contributors | Developer Guide → Contributing |

## Interactive Learning

### Jupyter Notebooks (19)

```bash
pip install -e .[notebooks]
jupyter notebook notebooks/
```

| Level | Notebooks | Topics |
|-------|-----------|--------|
| **Beginner** | 01-04 | Personas, workflows, dimensions, plugins |
| **Intermediate** | 05-08 | Event bus, collaboration, actions, governance |
| **Advanced** | 09-12 | Object model, CTO integration, orchestration, custom personas |
| **Expert** | 13-14 | Protocol integration, JV governance |
| **Expert** | 15-18 | Semantic search, knowledge graphs, RAG pipeline, unified object model |
| **Expert** | 19 | Evaluation and compliance (CLEAR+ benchmarks, model cards, EU AI Act) |

### Streamlit Apps (24)

```bash
pip install -e .[streamlit]
streamlit run apps/streamlit/persona_explorer.py
```

| App | Type | Description |
|-----|------|-------------|
| `learn_personas.py` | Educational | Step-by-step persona exploration |
| `persona_explorer.py` | Production | Full-featured persona browser with search, compare, network |
| `learn_workflows.py` | Educational | Workflow concepts and BFS traversal |
| `workflow_dashboard.py` | Production | Workflow graph visualization and simulation |
| `learn_object_model.py` | Educational | Repository[T], facade, evolution stages |
| `cto_concept_browser.py` | Production | Concept/element/association browsing |
| `mapping_explorer.py` | Production | Cross-vocabulary mapping browser |
| `learn_plugins.py` | Educational | Plugin types and ecosystem |
| `ecosystem_dashboard.py` | Production | Plugin registry and dependency graph |
| `collaboration_dashboard.py` | Production | Session browser and scoring visualization |
| `protocol_explorer.py` | Production | Protocol integration browser and A2A/MCP explorer |
| `demo_web_frontend.py` | Demo | Web frontend guided demo |
| `demo_distiller.py` | Demo | Distiller bridge guided demo |
| `demo_open_science.py` | Demo | Open science guided demo |
| `demo_skyparlour.py` | Demo | Sky-Parlour guided demo |
| `kg_explorer.py` | Production | Knowledge graph explorer and visualizer |
| `federated_dashboard.py` | Production | Federation dashboard with namespace browser |
| `tutorial_tracker.py` | Production | Tutorial progress tracker |
| `simulation_replay.py` | Production | Simulation event replay and analysis |
| `compliance_dashboard.py` | Production | Compliance audit dashboard with multi-regulation view |
| `benchmark_dashboard.py` | Production | CLEAR+ benchmark results and regression tracking |
| `compliance_audit_dashboard.py` | Production | EU AI Act compliance audit visualization |

### FCC Guidebook (20 chapters)

A comprehensive guidebook in `docs/guidebook/` covering all framework modules from introduction through evaluation, benchmarking, compliance, and governance, with 10 progressive labs and assessments.

### FCC Book Series (3 books, 24 chapters)

Three books in `docs/books/` provide deep coverage for different audiences: *Understanding FCC* (beginners), *Building with FCC* (developers), and *Advanced FCC* (researchers/architects).

### CTO Object Model Integration

```bash
pip install -e .[cto]  # Optional — all notebooks/apps work without CTO
```

The `fcc.objectmodel` module provides generalized Repository[T], ModelFacade, and VocabularyMapping patterns abstracted from CTO. Uses `typing.Protocol` for structural subtyping — works with both FCC frozen and CTO slotted dataclasses.

## Documentation

### Quick Start & Guides

- [GETTING_STARTED.md](GETTING_STARTED.md) — Beginner-friendly onboarding: install, first query, first simulation
- [QUICKSTART.md](QUICKSTART.md) — 60-second getting started guide
- [TUTORIALS_INDEX.md](TUTORIALS_INDEX.md) — Master catalog of all 19 notebooks, 24 apps, 15 demos, 20 chapters, 3 books
- [SAMPLE_PROMPTS.md](SAMPLE_PROMPTS.md) — 40 curated prompts across 4 difficulty tiers
- [PERSONA_INTERACTION_GUIDE.md](PERSONA_INTERACTION_GUIDE.md) — Visual guide to persona chains and champion orchestration
- [ARCHITECTURE_VISUAL_GUIDE.md](ARCHITECTURE_VISUAL_GUIDE.md) — Visual architecture walkthrough with screenshots

### Reference

- [ARCHITECTURE.md](ARCHITECTURE.md) — Detailed module walkthrough, data flow, and design decisions
- [CONTRIBUTING.md](CONTRIBUTING.md) — How to add personas, scenarios, templates, plugins, and more
- [GLOSSARY.md](GLOSSARY.md) — Comprehensive glossary of FCC terms and all 102 personas
- [CHANGELOG.md](CHANGELOG.md) — Release history and notable changes
- [ROADMAP.md](ROADMAP.md) — Project roadmap with detailed Phase 15 wave specifications
- [STRATEGIC_ARCHITECTURE_REVIEW.md](STRATEGIC_ARCHITECTURE_REVIEW.md) — Cross-project alignment and canonical authority

### Deep Dives

- [Ecosystem Integration Guide](docs/developer/ecosystem-integration-guide.md) — 10+ ecosystem project integration patterns
- [Protocol Architecture](docs/specification/protocol-architecture.md) — A2A, MCP, and AGENTS.md protocol design
- [Phase 12-15 Strategic Plan](docs/roadmap/PHASE_12_15_STRATEGIC_PLAN.md) — Wave-level roadmap through v1.0.0
- [Learning Paths](docs/getting-started/learning-paths.md) — Audience-specific guided routes
- [Sample Prompts](docs/tutorials/sample-prompts/) — 102 persona prompts, workflow orchestration, governance
- [Protocol Quickstart](docs/tutorials/protocol-quickstart.md) — Protocol integration getting started guide
- [Knowledge Federation Guide](docs/guidebook/ch17_knowledge_federation.md) — Semantic search, KG, and RAG guide
- [Book Series](docs/books/index.md) — 3 books, 24 chapters for all skill levels
- [Architecture Decision Records](docs/decisions/) — 5 ADRs documenting key design choices

### Audience Guides

- [For Beginners](docs/for-beginners/index.md) — Hello FCC tutorial, visual tour, essential glossary
- [For Educators](docs/for-educators/index.md) — 12-week curriculum, 2-day workshop, assessment strategies
- [For Scientists](docs/for-scientists/index.md) — FAIR workflow, literature review agents, reproducibility
- [For Professionals](docs/for-professionals/index.md) — Enterprise deployment, governance compliance, CI/CD integration

## Contributing

Contributions are welcome! Whether you are fixing a bug, adding a persona, improving documentation, building a plugin, or proposing a new feature, we would appreciate your help. Please read the [CONTRIBUTING.md](CONTRIBUTING.md) guide for development setup, code style, testing requirements, and the pull request process.

## License

MIT License. Copyright (c) INFORMATION COLLECTIVE, LLC. See [LICENSE](LICENSE) for details.
