recon_gen.common.handbook

Handbook templating support — vocabulary + diagram render hooks.

Public surface (BXa.1 trimmed): - HandbookVocabulary + InstitutionVocabulary - vocabulary_for(l2_instance) — single dispatch (no built-in

vocabularies post-BXa.1; institution name + acronym + investigation_personas come from the L2 YAML directly).

Removed in BXa.1 (doubly-dead per docs/audits/bx_persona_audit.md): - StakeholderVocabulary + MerchantVocabulary — hardcoded

tables that were never substituted in any docs page.

InvestigationPersonaVocabulary — replaced by the typed InvestigationPersona on L2Instance.investigation_personas.

class recon_gen.common.handbook.HandbookVocabulary(institution, investigation_personas, fixture_name=None, demo=<factory>)[source]

Bases: object

Substitution vocabulary handed to mkdocs-macros at render time.

BXa.1 (2026-05-30) trimmed stakeholders / merchants / gl_accounts / flavor — never substituted in any rendered page; the hardcoded production-code values that backed them (StakeholderVocabulary + MerchantVocabulary tables) went with them. If a future custom-prose template needs per-institution counterparty / merchant narrative, add a new top-level L2Instance field + extend this dataclass; don’t resurrect the hardcoded vocab path.

Parameters:

institution (InstitutionVocabulary)
investigation_personas (tuple[InvestigationPersona, ...])
fixture_name (str | None)
demo (DemoScenarioVocabulary)

demo: DemoScenarioVocabulary: Plant-derived demo accounts + Investigation scenario for walkthrough worked examples.

fixture_name: str | None = None: Bundled fixture name (e.g. "sasquatch_pr") when the active L2 IS a bundled fixture; None for integrator-supplied YAMLs. Used by handbook prose that references “the bundled <X> fixture”.

institution: InstitutionVocabulary

investigation_personas: tuple[InvestigationPersona, ...]

class recon_gen.common.handbook.InstitutionVocabulary(name, acronym, description)[source]

Bases: object

How the handbook refers to the institution.

Parameters:

name (str)
acronym (str)
description (str)

acronym: str: Short name — "SNB" / "the bank".

description: str: One-paragraph intro for handbook landing pages.

name: str: Full name — "Sasquatch National Bank" / "Your Institution".

recon_gen.common.handbook.vocabulary_for(l2_instance)[source]

Return the handbook vocabulary for l2_instance.

Single dispatch path post-BXa.1. Institution name + acronym + investigation-persona curated narrative all come from the L2 YAML directly; no special-case branches for bundled fixtures vs operator L2s.

Return type:: HandbookVocabulary
Parameters:: l2_instance (L2Instance)

recon_gen.common.handbook.vocabulary_for_l2(l2_instance)[source]

Build the handbook vocabulary from the L2 instance directly.

Return type:: HandbookVocabulary
Parameters:: l2_instance (L2Instance)

Precedence for the institution name: 1. l2_instance.institution_name if set (the BXa.1 promoted field

that operator L2s declare directly).

Regex-extracted from the L2’s description (the neutral fallback for L2s that omit institution_name).
"Your Institution" placeholder (when no description either).

Same precedence for acronym (explicit field → derived-from-name → "the institution" placeholder).

Modules

`diagrams`	Diagram render pipeline for the unified mkdocs site.
`invariants`	L1 invariants parser — AA.C.2.
`l2_triage_gaps`	L2 Triage + L2 Coverage Gaps parser — BU.2a (Lock 10).
`l2ft_exceptions`	L2FT Hygiene Exceptions parser — AA.C.4.
`vocabulary`	Handbook substitution vocabulary, built per-render from an L2 instance.