recon_gen.common.handbook.vocabulary

Handbook substitution vocabulary, built per-render from an L2 instance.

BXa.1 (2026-05-30) collapsed the prior Sasquatch-specific intercept into a single vocabulary_for_l2 builder. The institution name + acronym + curated investigation personas now live on the L2 YAML as top-level institution_name / institution_acronym / investigation_personas fields; the deleted persona block’s other slots (stakeholders, merchants, gl_accounts, flavor) were doubly dead — bypassed by the intercept AND not substituted in any docs page — so they went with the intercept.

The neutral fallback (regex-extracted institution name + “Your Institution” placeholder) survives for L2 YAMLs that omit institution_name. Empty investigation_personas is the same “no curated walkthrough content” signal the old empty-persona path carried — the handbook’s {% if vocab.demo.investigation.layering_chain %} gates already hide the walkthrough sections when no curated narrative is available.

Functions

`vocabulary_for`(l2_instance)	Return the handbook vocabulary for `l2_instance`.
`vocabulary_for_l2`(l2_instance)	Build the handbook vocabulary from the L2 instance directly.

Classes

`DemoAccount`(id, name)	An account demonstrated by a planted scenario.
`DemoScenarioVocabulary`([drift_account, ...])	Plant-derived demo content for walkthrough worked examples.
`HandbookVocabulary`(institution, ...[, ...])	Substitution vocabulary handed to mkdocs-macros at render time.
`InstitutionVocabulary`(name, acronym, description)	How the handbook refers to the institution.
`InvestigationScenarioVocabulary`(anchor, ...)	The Investigation app's planted scenario, normalized for prose.

class recon_gen.common.handbook.vocabulary.DemoAccount(id, name)[source]

Bases: object

An account demonstrated by a planted scenario.

id is the runtime account id (joins to the seed). name is a human-readable label for prose — falls back to the id when no description is available on the L2 account.

Parameters:

id (str)
name (str)

id: str

name: str

class recon_gen.common.handbook.vocabulary.DemoScenarioVocabulary(drift_account=None, overdraft_account=None, limit_breach_account=None, investigation=None)[source]

Bases: object

Plant-derived demo content for walkthrough worked examples.

Each field is None when the active L2 has no matching plants. Walkthrough templates use {% if vocab.demo.X %}...{% endif %} to hide their worked-example sections when the field is None.

Parameters:

drift_account (DemoAccount | None)
overdraft_account (DemoAccount | None)
limit_breach_account (DemoAccount | None)
investigation (InvestigationScenarioVocabulary | None)

drift_account: DemoAccount | None = None

property has_investigation_plants: bool

investigation: InvestigationScenarioVocabulary | None = None

limit_breach_account: DemoAccount | None = None

overdraft_account: DemoAccount | None = None

class recon_gen.common.handbook.vocabulary.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.vocabulary.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".

class recon_gen.common.handbook.vocabulary.InvestigationScenarioVocabulary(anchor, fanout_sender_count, layering_chain=(), anomaly_pair_sender=None)[source]

Bases: object

The Investigation app’s planted scenario, normalized for prose.

Only populated when the active L2 has at least one inv_fanout_plants entry; otherwise the parent DemoScenarioVocabulary.investigation is None and the Investigation worked-example admonitions don’t render.

Parameters:

anchor (DemoAccount)
fanout_sender_count (int)
layering_chain (tuple[DemoAccount, ...])
anomaly_pair_sender (DemoAccount | None)

anchor: DemoAccount: The recipient account the fanout converges on.

anomaly_pair_sender: DemoAccount | None = None: Optional sender of the volume-anomaly spike (Sasquatch’s Cascadia Trust Bank — Operations); None for L2s without one.

fanout_sender_count: int: Number of distinct senders in the recipient fanout.

layering_chain: tuple[DemoAccount, ...] = (): Optional shell-DDA layering chain (Sasquatch’s Shell A-B-C); empty for L2s without a hand-curated layering scenario.

recon_gen.common.handbook.vocabulary.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.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).