Cianfhoghlaim — long-distance, enduring learning. A research-and-deployment platform for the British Isles education corpus (8 nations × 5 stages × bilingual Goidelic + Brythonnic), agentic AI, self-hosted infrastructure, and minority-language machine learning. Maintained by Cian Mac an Déisigh Uí Liatháin (Deacy-Lyons), a Mathematics & Education teacher, Dioplóma C1 in Irish, and agentic-AI engineer based in Galway and East Belfast.

Useful companion resources: To understand the container, data, indexing, storage, and infrastructure patterns used throughout this project, see the hands-on labs at iximiuz Labs, the database references at DBQuacks, and the official documentation, blogs, and examples for CocoIndex, dlt, LanceDB, DuckDB, MotherDuck, Komodo, and Pangolin. These are useful external guides to the key technologies and design choices represented in the repository.

The 3 priority mise run tasks shipped by the 2026-07-30 → 2026-08-01 trilogy at a glance. Read this first; the full priority quick-refs are in AGENTS.md.

Plus the safety gate for any iac:bootstrap, iac:plan, or km deploy stack <arm-oci-*> from opencode: preflight:arm-oci (mandatory per the 2026-07-09 repo-boundary-lockdown openspec change).

The project is sprawling on purpose. It is a research-and-deployment platform for the British Isles education corpus, an agentic AI fleet, a self-hosted infrastructure mesh, and a minority-language ML playground — all federated by a single bun + uv + turbo monorepo. Because the goal is a deliberately overcomplicated Master's completed in a year, many subsystems that do work are partially obscured by the design choices meant for my team's downstream use. Read this section before forming an opinion about the repo.

The value for anyone looking at this project today is in the specific combinations of already well-calculated open-source packages. The data engineering (DLT + Dagster + BAML + CocoIndex + DuckLake + LanceDB + MotherDuck + Marimo), the DevOps (Komodo + Pangolin + Infisical + Locket + Pocket ID + Traefik + Garage S3), the web-development (TanStack Start + Convex + Hono + CopilotKit + oRPC + AG-UI + Cloudflare), and the agent layer (Agno + Google ADK + Pydantic AI + LiteLLM + Letta + Cognee + Graphiti + Langfuse + MLflow) are each real, working open-source compositions. You can copy any slice independently.

The 12-MCP agent surface is the new foundation layer (added 2026-08-21). All agent runtime tools are now wired via opencode.json

• .mcp.json with one canonical surface per domain — ccc for code search, firecrawl + crawl4ai + chrome for web data, dlt-workspace + motherduck for data engineering, cognee + graphiti + design-system for knowledge/memory, langfuse for observability, infisical for secrets, huggingface for model hub. See openspec/changes/2026-08-21-mcp-server-revival-overview.md for the canonical inventory.

You can take the same data pipelines and rewire them for any other jurisdiction. The dlt_sources/ + baml_src/ + cocoindex_flows/ + motherduck/ + notebooks/ stack already produces the official legal, medical, education, and government documents for the British Isles. Retargeting it for, say, the US CMS, the WHO IRIS repository, the Bundesministerium für Bildung, or the French Ministère de l'Éducation means changing the jurisdiction enum, the BAML schemas, the scrape cache roots, and the destination namespaces — the core pipeline shape stays the same. Use USE_LOCAL_SCRAPES=true while you rebuild; the curated cache at stedding/ingest_queue/ lets you iterate without spending scrape credits.

The cheapest way to do this is a cheap coding agent. A €20/month Gemini Deep Research Pro subscription is the right tool for the first hour (finding the authoritative ministry, exam-board, or medical-register endpoints). A MiniMax coding plan (or the local OpenCode Go CLI) is the right tool for the next two days (the iterative file-local refactor across dlt_sources/ + baml_src/ + cocoindex_flows/ + motherduck/). GitHub Copilot is a fine runner-up for single-file edits. None of them need the full monorepo.

Use my notes as a blueprint for your own deep-research tangent. The leabharlann repository (3.4 GB, 2,400+ docs × 7 subdirs) holds the source materials that informed every sub-agent, BAML schema, and CocoIndex flow in this repo. They are unique to my circumstances; treat them as a worked example of how to do a deep-research tangent in this domain, not as what to copy.

The full per-area deep-cuts report — what each package composes, which 3-5 files to copy, which 5 lines to change, which 1 assumption is hardest to escape, and which coding agent to point at which job — lives at docs/CHOP_AND_CHANGE_GUIDE.md.

⚠️ Important Disclaimer

The data engineering pipelines in this repository — DLT ingestion, BAML extraction, CocoIndex v1 embeddings, Cognee cognify passes, the 8 NCCA Leaving Certificate subject asset groups — process official Government syllabus exam papers + marking schemes of the Republic of Ireland (NCCA Leaving Certificate, Junior Cycle, Primary) and the wider British Isles education system. They are grounded in the 8 British Isles nations (Ireland, England, Scotland, Wales, Northern Ireland, Isle of Man, Jersey, Guernsey) and bilingualised in EN + GA (Gaeilge).

The web UIs (cianfhoghlaim-web, tuatha-ui, croilar-web, croilar-portal, oideachais, oideachais-dashboard, the tuatha-demo, game_showcase, the Hono API gateway) are packaged demos that prove the agentic-web wiring works. They are not yet the final pedagogical surface — the UI work is deferred until the data pipeline has produced the canonical syllabus-accurate assets.

To self-host your own instance you need your own domain name and a free Cloudflare account — see bonneagar/README.md.

cianfhoghlaim is a polyglot monorepo (bun + uv + turbo) that:

1. Ingests the curriculums, exam papers, marking schemes, and syllabi of the 8 British Isles nations (with bilingual EN + GA extraction for the Irish strand).
2. Extracts structured data via the BAML schema library at baml_src/british_isles/ (NCCA, SEC, CCEA, SQA, WJEC, Edexcel + the European Union EUR-Lex / ECDC / EMA / Eurostat / Eurydice + multi-nation Commonwealth + Americas expansions).
3. Embeds in vector + graph form via 60 CocoIndex v1 Apps (7 model families) + Cognee cognify layers + the Graphiti temporal knowledge graph.
4. Surfaces through marimo reactive notebooks, MotherDuck Dives, TanStack Start web apps, and a 13-agent meaisínfhoghlaim fleet (LiteLLM-routed via the OpenCode Go API; 7-tier fallback alias minimax).
5. Hosts itself on a self-managed 93-stack Docker Compose fleet (bunchloch MacBook M4 Max for the data plane + arm1-oci Oracle Cloud free-tier for the control plane + Garage S3 storage + the Komodo / Pangolin / Infisical / Locket / Pocket ID / TinyAuth / Traefik mesh).

The author is a registered member of the Teaching Council, with verified memberships in Fine Gael and the Alliance Party of Northern Ireland, and the Deacy Tribe of the Morris-Conroy tribes of Galway. See the Personal credential corpus section below for the full verified-PDF table, the Verified academic archive section for the leabharlann/ subdir summary, and the Family history section for the Triple-Crown synthesis.

The platform has one canonical source of truth for every model, schema, pipeline, and stack (post-2026-08-15). It replaces the ~70 hardcoded model strings + 96 hand-written Pydantic duplicates + 54 nearly-identical CocoIndex Apps that the audit found.

The 4 canonical artifacts:

• meaisinfhoghlaim/models/model_registry.py — the 60-entry MODEL_REGISTRY across 7 families (ocr_vision × 20 / text_llm × 21 / embedder × 3 / rerank × 3 / image_gen × 5 / voice × 5 / translation × 3).
• notebooks/_shared/schema.py — the 5 introspection helpers (schema_introspect, schema_introspect_table, list_dlt_sources, list_cocoindex_apps, list_baml_classes).
• notebooks/00_control_panel.py — the 5-tab marimo control panel (Models / Pipelines / Datasets / Stacks / Registry).
• deployment-choice.yaml — the canonical enablement file (read/written by the notebook + web UI + CLI).
• opencode.json — the 12-MCP agent surface (added 2026-08-21). One canonical entry per domain: ccc / firecrawl / crawl4ai / chrome / dlt-workspace / motherduck / cognee / graphiti / design-system / langfuse / infisical / huggingface.

The 4 supporting artifacts:

• scripts/registry_audit.py — drift detector (fails CI on hardcoded model strings).
• agents/adk/litellm_agent.py — make_litellm_agent() + litellm_model("minimax") wrappers.
• orchestration/defs/2_materials/_base/jurisdiction_assets_base.py — the JurisdictionAssetsBase for the per-jurisdiction Dagster asset wrappers.
• 3 CocoIndex factories (cocoindex_flows/european_nations/_factory.py et al.).

The canonical model_for() pattern:

from meaisinfhoghlaim.models import model_for

default = model_for("text_llm", "default")              # → "minimax-m3"
irish   = model_for("text_llm", "irish")                # → "uccix-mistral-24b"
embed   = model_for("embedder", "default")              # → "BAAI/bge-m3"

The canonical schema_introspect() pattern:

from notebooks._shared.schema import schema_introspect, list_dlt_sources
conn = ibis.duckdb.connect("md:cianfhoghlaim")
rows = schema_introspect(conn)             # every BIEP DuckDB table's columns
print(f"{len(list_dlt_sources())} DLT sources, {len(rows)} columns")

Lint gate: mise run lint:registry — fails on any hardcoded model string in agents/, baml_src/, notebooks/, web/, orchestration/, meaisinfhoghlaim/.

Full guide: .agents/skills/centralized-registry/SKILL.md.

Two language graphs live side by side, orchestrated by turbo.json and a single mise.toml toolchain. Post-v7 (2026-07-17), the Python package IS the repo root — no more cianfhoghlaim/ nesting.

The GitOps infrastructure lives in bonneagar/ and is reached via bun run --cwd bonneagar iac:<command> from the root package.json. The IaC is no longer a separate GitHub repo; the archive-bonneagar remote is a frozen read-only relic. See bonneagar/README.md for the full architecture, the 93-stack inventory, the 7-day operator quick start, and the known gaps.

The pipeline walks a corpus from raw disk to an agent-consumable, semantically-indexed artifact. Five sequential stages live under orchestration/defs/<stage>/, with two 4_* siblings alongside 4_asset_generation/ for budget tracking and the docs-index memory job:

Each stage has a matching Component class in orchestration/components/ that dg-style YAML defs.yaml files instantiate (11 components in total; see orchestration/README.md for the architecture, the JurisdictionAssetsBase pattern, and the R1–R4 conformance check at scaffold time).

The 6 Irish LC priority subjects — Mathematics, Chemistry, Geography, Gaeilge, English, Computer Science — get the deep treatment: NCCA syllabus + SEC exam papers + marking schemes + 7 v1 CocoIndex flows + 42 Dagster assets + 6 marimo notebooks + 4 MotherDuck Dives + a daily MotherDuck Flight.

The BAML extraction schemas (baml_src/british_isles/ireland/education/lc_extraction/*.baml) produce structured LeavingCertSyllabus, LeavingCertPastPaper, LeavingCertMarkingScheme objects — rubric-anchored to NCCA PDF page references. Web search by the agent fleet always lands on an in-pipeline asset, never on a stale URL.

For the wider corpus (Junior Cycle, Primary, the 5 English boards, SQA, WJEC, CCEA, plus the EU EUR-Lex / ECDC / EMA / Eurostat / Eurydice + multi-nation Commonwealth + Americas expansions), the same JurisdictionAssetsBase pattern scales to ~30-line per-jurisdiction subclasses instead of ~380-line hand-written asset files.

The 13 root agents (1 Custom + 8 ADK + 3 Agno + 1 image-generation) plus the 8 NCCA Leaving Cert subject specialists (gael_agent, math_agent, appm_agent, chem_agent, comp_agent, engl_agent, geog_agent, hist_agent) all route through the LiteLLM gateway at litellm.cianfhoghlaim.ie:4000 and the canonical 7-tier minimax fallback alias. The fleet spans 5 frameworks (Custom + ADK + Agno + Pipecat + CopilotKit), wires through a single canonical surface (AGENT_REGISTRY), and is observed by a 5-layer observability stack (Langfuse + Logfire + MLflow + RAGAS + structlog) backed by a 5-backend memory layer (Cognee + Graphiti

• LanceDB + FalkorDB + Memgraph). See agents/README.md for the architecture diagram
• implementation decisions + how to lift a single agent out independently.

These are the records that ground the project's claims. The full long-form index lives at cian_mac_an_déisigh_uí_liatháin/README.md; this table is the canonical subset a new visitor needs to verify the author + the lineage:

The course material + examination scripts + the personal academic corpus live at github.com/cianfhoghlaim/leabharlann — a separate 3.4 GB repo, the only remaining separately-managed repo. It contains 7 top-level subdirectories that feed the data platform:

The Tuatha educational MMO's Ard-Rí na hÉireann framing is grounded in 7 long-form research PDFs under leabharlann/gemini_deep_research/culture/:

1. claiming_rí_na_gaillimhe_a_synthesis.pdf — Rí na Gaillimhe: An Ethnohistorical and Jurisprudential Warrant (15 pp.)
2. heraldic_research_for_dual_blood_lineage.pdf — The Heraldry of the Corrib Crown (14 pp.)
3. british_isles_cianfhoghlaim.pdf — Strategic Blueprint for Inter-Celtic Linguistic Acquisition, AI Integration, and Transnational Educator Credentialing (16+ pp.)
4. claiming_irish_kingship_through_lineage.pdf — The Crown of the Corrib: An Ethnohistorical and Genealogical Warrant (13 pp.)
5. researching_neil_deacy's_galway_heritage.pdf — The Socio-Economic, Athletic, and Genealogical Topography of the Deacy Family in Galway (12 pp.)
6. royal_titles_celtic_heritage_and_claims.pdf — The Crown of the Corrib and the Imperium of the Irish Sea (13 pp.)
7. deacy_family_heritage_research.pdf — The Deacy and Conroy Dynasties: An Ethnohistorical Analysis of Galway's Commercial and Maritime Lineage (9 pp.)

The author's lineage is the triple-crown union of four kindreds of Connacht and Munster:

1. Deacy (maternal surname; Irish Uí Dhéisigh) — the sept of the Déisi Muman resettled in south Connacht (Co. Galway) during the 12th century; the family gave their name to the late Éamonn Deacy and the Eamonn Deacy Park in Galway.
2. Lyons (paternal grandfather's lineage; Irish Mac Liatháin) — the Uí Liatháin sept of Munster, who (per the Historia Brittonum) colonized Wales and Cornwall alongside the proto-Déisi.
3. Morris (maternal great-grandmother Christina Morris) — of the City of Tribes merchant families of Galway.
4. Conroy (maternal great-great-grandmother Polly Conroy; Irish Mac Conraoi / Ó Conaire) — the Sea-Kings of Connacht who held the tuath of Delbhna Tír Dhá Locha (the barony of Moycullen in Connemara). Polly Conroy was a cousin of Pádraic Ó Conaire, the canonical modern Irish-language writer from Galway.

The 3-stream synthesis is the 4-line modern incarnation: Cian Mac an Déisigh Uí Liatháin (Deacy-Lyons). The Deacy side carries the galwegian-historical pedigree (Cooke's Corner, Aston Villa, Galway United, Eamonn Deacy Park). The Lyons side carries the pan-Munster-Brythonic-imperial pedigree (Uí Liatháin of Castlelyons and the Welsh / Cornish colonies). The hyphenation preserves both branches of the Triple Crown and acknowledges the previous achievement of the Lyons lineage while respecting the author's choice to bear his mother's Mac an Déisigh name first.

The full discursive narrative — the Triple-Crown synthesis, the Brehon-Law saoí framing, the sacred topography of Shantalla (Sean Talamh), the mythological warrant of Cian mac Cáinte (the swine-god and father of Lugh Lámhfhada), the philological restoration of the Aos Sídhe vow, and the dual-monarchy synthesis with King Charles III — lives at cian_mac_an_déisigh_uí_liatháin/FAMILY_HISTORY.md (619 lines, preserved verbatim per the author's prior instruction that "the validated references to my credentials and family history relevant to the name and location of the project" stay in the repo).

The archive-bonneagar remote at github.com/cianfhoghlaim/bonneagar.git is frozen — no further commits will be pushed; its history is preserved in-tree.

openspec/ is the single source of truth for capability specs. The workflow: list → write proposal/tasks/spec deltas → validate --strict → implement → archive. 96 specs live under openspec/specs/; 34 changes are currently pending under openspec/changes/. See openspec/AGENTS.md for the full workflow and openspec/project.md for conventions.

openspec list --specs                    # 96 capability specs
openspec list                            # 34 pending changes
openspec validate <change-id> --strict   # MUST pass before commit
openspec archive <change-id> --yes       # after deploy

The 3-way contract: the dev-baile Infisical vault is the source of truth → the committed .infisical.env template holds every value as an infisical://dev-baile/... reference → the gitignored .env is hydrated by mise directory hooks + the Locket sidecar at runtime. The IaC binds each stack's secrets.env to Infisical via the typed InfisicalClient at bonneagar/iac/clients/. Full guide: bonneagar/SECRETS-MANAGEMENT.md.

CCC (bun run ccc:search "<query>") gives every agent a per-project semantic index at .cocoindex_code/target_sqlite.db (CocoIndex BGE-M3 embeddings over ~7,000 tracked files). Cognee (cognee cognify) gives a knowledge-graph memory layer at agents/meaisinfhoghlaim/memory/ across 7 clusters. Firecrawl (firecrawl_search / firecrawl_scrape / firecrawl_research_*) covers upstream + biomedical + arXiv literature. Per the 2026-08-14 dual-search convention, every Firecrawl call MUST be paired with a ccc:search so both tool names appear in the Langfuse trace.

Agentically. The canonical configuration is at opencode.json. The 13 + 8 agent fleet is wired through agents/agent_registry.py:AGENT_REGISTRY with a single canonical surface (the same conventions as agents/tuatha/wiring.py:SubjectAgentWiring). See AGENTS.md for the durable rules every coding agent follows in this repo.

Business Source License 1.1 — see LICENSE.md. Granted for non-commercial, non-profit, cultural preservation, and academic research use within the legal jurisdictions of Ireland, Northern Ireland, the United Kingdom, the European Union, the British Isles, the Commonwealth, the Crown, the United States of America, Mexico, Brazil, Taiwan, Tibet, Nepal, South Korea, Japan, and China.

Excludes: sanctioned organisations, paramilitary groups, entities in violation of international human rights conventions. Change Date: 4 years from publication. Change License: AGPL v3.0.

Start here. The canonical onboarding doc is NEW-USER-ONBOARDING.md (~380 lines: 1-command setup + the 10-step cluster bringup + the 12-MCP verification checklist + the 3 secrets + the troubleshooting FAQ). The 60-second quick path is CHEATSHEET.md.

The per-stack onboarding scripts (Pocket ID + Komodo + Pangolin for the auth mesh; Tuatha + SpacetimeDB for the educational MMO) live in their respective hub READMEs rather than the root, to keep this entry-point scannable:

• Pocket ID + Komodo + Pangolin (single-Passkey login mesh) → AGENTS.md § opencode-safety + bonneagar/README.md
• Tuatha Educational MMO (Babylon.js + FastAPI + TanStack UI) → tuatha/README.md
• BIEP data platform (DLT + Dagster + BAML + CocoIndex + MotherDuck) → orchestration/README.md + dlt_sources/DATA_PLATFORM_ROUTER.md
• Self-host a fresh cluster → bonneagar/README.md (the 6-step operator quick start)
• Onboarding wizard (the 3-credentials TUI) → scripts/onboard-pocketid.sh

Agent Telemetry (Last Updated: 2026-07-29 22:30:52 UTC)

• Total Cached Structural Documents: 0
• Examinations.ie Cache: 0 files
• NCCA.ie Cache: 0 files
• CurriculumOnline Cache: 0 files