Migration Tutorials¶

These four tutorials cover every migration path a team can hit when adopting, upgrading, or aligning with FCC v1.5. They are deliberately separate because the audiences + time budgets differ — pick the one that matches your situation and ignore the others until you need them.

The four tutorials¶

Tutorial	Who	Time	When to pick
Restructuring existing documentation	Docs Lead, Technical Writer, Architect	4-6 h first pass; 2-3 days full retrofit	You have a mature docs tree (dozens-to-hundreds of files) and want to retrofit it onto FCC R.I.S.C.E.A.R.-aligned structure without a full rewrite.
Integrating FCC into a mature codebase	Engineering Lead, DevOps, Platform	1-2 days CI; 1 week full rollout	You have a production codebase + CI and want to add FCC as a first-class dependency without disrupting the dev loop.
Upgrading consumers to v1.5 stable	Downstream consumer, plugin author	2-4 h per package	You consumed POLARIS or LYRA via `fcc.plugins.v1_5_preview.` during the v1.4.x preview window and need to move to the stable `fcc.api.` surface before v1.6.0.
Adopting universal services	Ecosystem partner, Integration Lead	3-5 days over a quarter	You are a downstream consumer (PAOM, ice_ext, a constellation vertical, a JV library) aligning with the 16-entry universal services superset.

When to pick which¶

You are reading FCC for the first time and asking "does this fit my project?" — read restructuring existing documentation for the docs angle or integrating FCC into a mature codebase for the engineering angle. Both answer the "how much change is this really?" question honestly.

Your team already pip-installs FCC and writes scenarios, but you are on 1.4.x and need to upgrade. — read upgrading consumers to v1.5 stable. It is the shortest of the four; you may finish in an afternoon.

You are one of the known FCC consumers (PAOM, ice_ext, a constellation vertical, ATHENIUM, MNEMOSYNE) or a future equivalent. — read adopting universal services. This tutorial codifies the cross-ecosystem contract you are signing.

You are building an in-house plugin or custom persona for an existing FCC deployment. — start with integrating FCC into a mature codebase, Step 3 (custom persona registration). The other migration tutorials are not prerequisite.

Sequencing recommendation¶

If your team needs multiple tutorials, do them in this order:

Integrating FCC into a mature codebase — gives you the baseline pip install, CI, custom persona registration, and observability wiring.
Restructuring existing documentation — if you have a docs tree, retrofit it onto the audience-tier cascade + PHOENIX gates now that FCC is live in your CI.
Upgrading consumers to v1.5 stable — only relevant if you have v1.4.x preview imports.
Adopting universal services — only relevant for cross-ecosystem consumers. Run this after your baseline integration is stable.

Steps 1 + 2 are typically done together by the same team. Steps 3 + 4 are ecosystem-facing work handled by a different (usually smaller) group.

Shared prerequisites¶

Every migration tutorial assumes:

Python 3.10 or higher.
pip install fcc-agent-team-ext>=1.5.0,<2.0.0.
Familiarity with the FCC fundamentals tutorials — at least tutorials 1–3.
A working installation that passes python -c "import fcc; print(fcc.__version__)".

Familiarity with the codename decoder is helpful but not required — every tutorial links back to the decoder the first time it uses a codename (PHOENIX, POLARIS, LYRA, NEXUS, AURORA, CONSTEL, AOME, PAOM, DISTILLER, ATHENIUM, MNEMOSYNE, and the ten constellation verticals).

Shared conventions¶

All four tutorials follow the same conventions:

YAML front matter with audience, tier, estimated-time keys
optional persona + workflow keys for cross-reference.
Numbered steps (Step 1, Step 2, ...) with code blocks per step.
Checklist-for-done at the bottom of each tutorial.
Next steps linking to related migration tutorials + relevant ADRs.
Common pitfalls section explaining the most frequent mistakes teams make on the migration.