api-reference.md

# API Reference

> **API documentation** for all infrastructure modules

**Quick Reference:** [Modules Guide](../modules/modules-guide.md) | [Infrastructure Docs](../../infrastructure/AGENTS.md) | [Getting Started](../guides/getting-started.md)

This document provides the API reference for all public functions and
classes exported by `infrastructure/<pkg>/__init__.py`. All modules
follow the thin-orchestrator pattern.

**Note**: These modules are part of the infrastructure layer. For
project-specific code, see `projects/{name}/src/`.

## How this file is maintained

The per-package symbol listings below are generated between the
`BEGIN:API_REFERENCE` and `END:API_REFERENCE` markers by
`scripts/docgen/api_reference.py`. Do not edit the generated block by hand.
<!-- BEGIN:API_REFERENCE -->
<!-- This block is generated by `scripts/docgen/api_reference.py` from each package's `__init__.py` `__all__`. Do not hand-edit. Hand-written prose belongs **above** the markers. -->

## Package: `infrastructure.autoresearch`

### `AutoResearchConfig`

*symbol — defined in `infrastructure.autoresearch`*

### `AutoResearchIssue`

*symbol — defined in `infrastructure.autoresearch`*

### `AutoResearchOrchestrator`

*symbol — defined in `infrastructure.autoresearch`*

### `AutoResearchPlan`

*symbol — defined in `infrastructure.autoresearch`*

### `AutoResearchReport`

*symbol — defined in `infrastructure.autoresearch`*

### `AutoResearchStage`

*symbol — defined in `infrastructure.autoresearch`*

### `BenchmarkTask`

*symbol — defined in `infrastructure.autoresearch`*

### `BudgetPolicy`

*symbol — defined in `infrastructure.autoresearch`*

### `build_autoresearch_plan`

*symbol — defined in `infrastructure.autoresearch`*

### `EvidenceLink`

*symbol — defined in `infrastructure.autoresearch`*

### `ExperimentCandidate`

*symbol — defined in `infrastructure.autoresearch`*

### `EXTRINSIC_QUALITY_CHECKS`

*symbol — defined in `infrastructure.autoresearch`*

### `INTRINSIC_QUALITY_CHECKS`

*symbol — defined in `infrastructure.autoresearch`*

### `load_autoresearch_config`

*symbol — defined in `infrastructure.autoresearch`*

### `mad_confidence`

*symbol — defined in `infrastructure.autoresearch`*

### `metric_unit_from_name`

*symbol — defined in `infrastructure.autoresearch`*

### `OrchestrationEvent`

*symbol — defined in `infrastructure.autoresearch`*

### `OrchestrationResult`

*symbol — defined in `infrastructure.autoresearch`*

### `parse_metric_lines`

*symbol — defined in `infrastructure.autoresearch`*

### `parse_string_sequence`

*symbol — defined in `infrastructure.autoresearch`*

### `ResearchIdea`

*symbol — defined in `infrastructure.autoresearch`*

### `ResearchProgram`

*symbol — defined in `infrastructure.autoresearch`*

### `ReviewGate`

*symbol — defined in `infrastructure.autoresearch`*

### `RunLedger`

*symbol — defined in `infrastructure.autoresearch`*

### `SecurityProfile`

*symbol — defined in `infrastructure.autoresearch`*

### `validate_autoresearch_overlay`

*symbol — defined in `infrastructure.autoresearch`*

### `validate_autoresearch_plan`

*symbol — defined in `infrastructure.autoresearch`*

### `ValidationPhase`

*symbol — defined in `infrastructure.autoresearch`*

### `write_autoresearch_report`

*symbol — defined in `infrastructure.autoresearch`*

## Package: `infrastructure.benchmark`

### `BenchmarkCheckResult`

*symbol — defined in `infrastructure.benchmark`*

### `BenchmarkManifest`

*symbol — defined in `infrastructure.benchmark`*

### `BenchmarkScore`

*symbol — defined in `infrastructure.benchmark`*

### `load_benchmark_manifest`

*symbol — defined in `infrastructure.benchmark`*

### `RubricScore`

*symbol — defined in `infrastructure.benchmark`*

### `RubricSet`

*symbol — defined in `infrastructure.benchmark`*

### `run_benchmark_manifest`

*symbol — defined in `infrastructure.benchmark`*

### `score_project_against_manifest`

*symbol — defined in `infrastructure.benchmark`*

### `score_rubric`

*symbol — defined in `infrastructure.benchmark`*

### `scores_to_dict`

*symbol — defined in `infrastructure.benchmark`*

### `scores_to_markdown`

*symbol — defined in `infrastructure.benchmark`*

### `write_default_manifest`

*symbol — defined in `infrastructure.benchmark`*

## Package: `infrastructure.doctor`

### `build_plans_for_findings`

*function — defined in `infrastructure.doctor.fixers`*

```python
build_plans_for_findings(findings: list[Finding], state: DoctorState, *, max_therapy: TherapyLevel=TherapyLevel.CONSERVATIVE, selected_codes: frozenset[str] | None=None, selected_fix_ids: frozenset[str] | None=None) -> list[FixPlan]
```

Translate findings into a deduplicated, ordered list of plans.

### `compute_exit_code`

*function — defined in `infrastructure.doctor.reporter`*

```python
compute_exit_code(findings: Iterable[Finding]) -> int
```

Map the worst finding severity into a stable exit code.

### `compute_scorecard`

*function — defined in `infrastructure.doctor.scorecard`*

```python
compute_scorecard(findings: Iterable[Finding]) -> tuple[float, dict[str, float]]
```

Return ``(overall, per_dimension)`` 0–100 scores.

### `DETECTORS`

*symbol — defined in `infrastructure.doctor.detectors`*

### `DIMENSION_WEIGHTS`

*constant — defined in `infrastructure.doctor.scorecard`*

```python
DIMENSION_WEIGHTS: dict[str, float] = {'environment': 2.0, 'project_layout': 2.0, 'hygiene': 1.0, 'tooling_state': ...
```

### `DIMENSIONS`

*constant — defined in `infrastructure.doctor.scorecard`*

```python
DIMENSIONS: dict[str, str] = {'DOC1': 'environment', 'DOC2': 'project_layout', 'DOC3': 'hygiene', 'DOC4': ...
```

### `DoctorReport`

*class — defined in `infrastructure.doctor.models`*

```python
class DoctorReport
```

Aggregate result of one doctor run.

### `DoctorSafetyError`

*class — defined in `infrastructure.doctor.safety`*

```python
class DoctorSafetyError(RuntimeError)
```

Raised when the safety contract cannot be honoured.

### `DoctorState`

*class — defined in `infrastructure.doctor.safety`*

```python
class DoctorState(repo_root: Path)
```

Filesystem layout for doctor state.

### `EXIT_CRITICAL`

*constant — defined in `infrastructure.doctor.reporter`*

```python
EXIT_CRITICAL = 3
```

### `EXIT_ERROR`

*constant — defined in `infrastructure.doctor.reporter`*

```python
EXIT_ERROR = 2
```

### `EXIT_HEALTHY`

*constant — defined in `infrastructure.doctor.reporter`*

```python
EXIT_HEALTHY = 0
```

### `EXIT_REGRESSION`

*constant — defined in `infrastructure.doctor.reporter`*

```python
EXIT_REGRESSION = 4
```

### `EXIT_USAGE`

*constant — defined in `infrastructure.doctor.reporter`*

```python
EXIT_USAGE = 64
```

### `EXIT_WARN`

*constant — defined in `infrastructure.doctor.reporter`*

```python
EXIT_WARN = 1
```

### `Finding`

*class — defined in `infrastructure.doctor.models`*

```python
class Finding
```

Outcome of one read-only detector.

### `FIXER_REGISTRY`

*constant — defined in `infrastructure.doctor.fixers`*

```python
FIXER_REGISTRY: dict[str, FixerFn] = {'fix_make_run_sh_executable': build_fix_make_run_sh_executable, 'fix_clean_p...
```

### `FixPlan`

*class — defined in `infrastructure.doctor.models`*

```python
class FixPlan
```

Declarative description of an intended mutation.

### `load_journal`

*function — defined in `infrastructure.doctor.safety`*

```python
load_journal(state: DoctorState) -> list[MutateRecord]
```

Return every record in the journal, oldest first.

### `mutate`

*function — defined in `infrastructure.doctor.safety`*

```python
mutate(plan: FixPlan, state: DoctorState) -> MutateRecord
```

Execute ``plan`` under the full safety contract.

### `MutateRecord`

*class — defined in `infrastructure.doctor.models`*

```python
class MutateRecord
```

Audit record produced by the mutate() chokepoint.

### `register_handler`

*function — defined in `infrastructure.doctor.safety`*

```python
register_handler(action_kind: str, handler: ActionHandler) -> None
```

Register an :class:`ActionHandler` for ``action_kind``.

### `render_report_json`

*function — defined in `infrastructure.doctor.reporter`*

```python
render_report_json(report: DoctorReport, *, indent: int | None=2) -> str
```

Render the report as JSON for agent consumption.

### `render_report_text`

*function — defined in `infrastructure.doctor.reporter`*

```python
render_report_text(report: DoctorReport) -> str
```

Render the full report as a text block.

### `RepairLevel`

*class — defined in `infrastructure.doctor.models`*

```python
class RepairLevel
```

One available therapy for a finding.

### `run_detectors`

*symbol — defined in `infrastructure.doctor.detectors`*

### `Severity`

*class — defined in `infrastructure.doctor.models`*

```python
class Severity(IntEnum)
```

Ordered diagnostic severity. Higher = worse.

### `TherapyLevel`

*class — defined in `infrastructure.doctor.models`*

```python
class TherapyLevel(IntEnum)
```

How radical a fixer is.

### `undo`

*function — defined in `infrastructure.doctor.safety`*

```python
undo(record: MutateRecord, state: DoctorState) -> MutateRecord
```

Restore the filesystem to the pre-mutation state for ``record``.

## Package: `infrastructure.documentation`

### `ApiEntry`

*class — defined in `infrastructure.documentation.glossary_gen`*

```python
class ApiEntry
```

Represents a public API entry from source code.

### `build_api_index`

*function — defined in `infrastructure.documentation.glossary_gen`*

```python
build_api_index(src_dir: str) -> list[ApiEntry]
```

Scan `src_dir` and collect public functions/classes with summaries.

### `build_generated_figure_registry`

*function — defined in `infrastructure.documentation.generated_figure_registry`*

```python
build_generated_figure_registry(specs: Iterable[FigureSpecLike], generated_paths: Iterable[Path], *, schema_version: str) -> dict[str, object]
```

Build a deterministic registry after checking every declared figure.

### `FigureManager`

*class — defined in `infrastructure.documentation.figure_manager`*

```python
class FigureManager(registry_file: str | None=None)
```

Register, retrieve, and persist figure metadata by label.

### `FigureMetadata`

*class — defined in `infrastructure.documentation.figure_manager`*

```python
class FigureMetadata
```

Metadata for a figure.

### `FigureRegistryError`

*class — defined in `infrastructure.documentation.generated_figure_registry`*

```python
class FigureRegistryError(ValueError)
```

Raised when generated figures cannot satisfy their registry contract.

### `FigureSpecLike`

*class — defined in `infrastructure.documentation.generated_figure_registry`*

```python
class FigureSpecLike(Protocol)
```

Structural contract for project-owned figure specifications.

### `generate_markdown_table`

*function — defined in `infrastructure.documentation.glossary_gen`*

```python
generate_markdown_table(entries: list[ApiEntry]) -> str
```

Generate a Markdown table from API entries.

### `publish_generated_figures`

*function — defined in `infrastructure.documentation.generated_figure_registry`*

```python
publish_generated_figures(output_dir: Path, specs: Iterable[FigureSpecLike], generated_paths: Iterable[Path], *, schema_version: str) -> list[Path]
```

Validate, mirror, and register a complete generated figure set.

### `write_generated_figure_registry`

*function — defined in `infrastructure.documentation.generated_figure_registry`*

```python
write_generated_figure_registry(registry_path: Path, specs: Iterable[FigureSpecLike], generated_paths: Iterable[Path], *, schema_version: str) -> Path
```

Validate generated files and atomically write their registry JSON.

## Package: `infrastructure.fonds`

### `build_fond_info`

*function — defined in `infrastructure.fonds.fonds_info`*

```python
build_fond_info(fond_dir: Path, program: str='') -> FondInfo
```

Build a FondInfo from a validated fond directory.

### `discover_fonds`

*function — defined in `infrastructure.fonds.discovery`*

```python
discover_fonds(repo_root: Path | str) -> list[FondInfo]
```

Discover all valid fonds in the fonds/ directory.

### `FondInfo`

*class — defined in `infrastructure.fonds.fonds_info`*

```python
class FondInfo
```

Information about a discovered fond.

### `resolve_fond_root`

*function — defined in `infrastructure.fonds.discovery`*

```python
resolve_fond_root(repo_root: Path | str, fond_name: str) -> Path
```

Resolve a fond directory by qualified name.

### `validate_fond_structure`

*function — defined in `infrastructure.fonds.validation`*

```python
validate_fond_structure(fond_dir: Path) -> tuple[bool, str]
```

Validate that fond has the required structure.

## Package: `infrastructure.formal_contracts`

### `ALL_BLOCK_TYPES`

*symbol — defined in `infrastructure.formal_contracts`*

### `Block`

*symbol — defined in `infrastructure.formal_contracts`*

### `check_manuscript`

*symbol — defined in `infrastructure.formal_contracts`*

### `Claim`

*symbol — defined in `infrastructure.formal_contracts`*

### `compose`

*symbol — defined in `infrastructure.formal_contracts`*

### `compose_manuscripts`

*symbol — defined in `infrastructure.formal_contracts`*

### `CompositionError`

*symbol — defined in `infrastructure.formal_contracts`*

### `Dataset`

*symbol — defined in `infrastructure.formal_contracts`*

### `DependencyEdge`

*symbol — defined in `infrastructure.formal_contracts`*

### `Derivation`

*symbol — defined in `infrastructure.formal_contracts`*

### `Diagnostic`

*symbol — defined in `infrastructure.formal_contracts`*

### `EdgeKind`

*symbol — defined in `infrastructure.formal_contracts`*

### `EMPTY_MANUSCRIPT`

*symbol — defined in `infrastructure.formal_contracts`*

### `Evidence`

*symbol — defined in `infrastructure.formal_contracts`*

### `EvidenceTier`

*symbol — defined in `infrastructure.formal_contracts`*

### `Figure`

*symbol — defined in `infrastructure.formal_contracts`*

### `FormalCode`

*symbol — defined in `infrastructure.formal_contracts`*

### `FormalStatement`

*symbol — defined in `infrastructure.formal_contracts`*

### `Manuscript`

*symbol — defined in `infrastructure.formal_contracts`*

### `MatchPolicy`

*symbol — defined in `infrastructure.formal_contracts`*

### `read_blocks`

*symbol — defined in `infrastructure.formal_contracts`*

### `ReaderError`

*symbol — defined in `infrastructure.formal_contracts`*

### `Report`

*symbol — defined in `infrastructure.formal_contracts`*

### `Section`

*symbol — defined in `infrastructure.formal_contracts`*

### `Table`

*symbol — defined in `infrastructure.formal_contracts`*

## Package: `infrastructure.llm`

### `generate_review_with_metrics`

*function — defined in `infrastructure.llm.review.generation`*

```python
generate_review_with_metrics(client: LLMClient, text: str, review_type: ReviewType, review_name: str, template_class: 'type[ResearchTemplate]', model_name: str='', temperature: float=0.3, max_tokens: int | None=None, max_retries: int=1) -> tuple[str | None, ReviewMetrics]
```

Generate a review using a specified template and record execution metrics.

### `GenerationOptions`

*class — defined in `infrastructure.llm.core.config`*

```python
class GenerationOptions
```

Per-query generation options for LLM requests.

### `get_template`

*function — defined in `infrastructure.llm.templates`*

```python
get_template(name: str) -> ResearchTemplate
```

Get a template by name.

### `is_off_topic`

*function — defined in `infrastructure.llm.validation.format`*

```python
is_off_topic(text: str) -> bool
```

Check if response contains off-topic indicators.

### `LLMClient`

*class — defined in `infrastructure.llm.core.client`*

```python
class LLMClient(config: OllamaClientConfig | None=None)
```

Client for interacting with LLM providers (Ollama).

### `OllamaClientConfig`

*class — defined in `infrastructure.llm.core.config`*

```python
class OllamaClientConfig(**kwargs: Any)
```

Configuration for LLM interaction.

### `validate_complete`

*function — defined in `infrastructure.llm.validation.core`*

```python
validate_complete(content: str, mode: ResponseMode=ResponseMode.STANDARD, schema: dict[str, Any] | None=None) -> bool
```

Validate LLM response content based on the response mode.

## Package: `infrastructure.metadata`

### `ebook_metadata_from_config`

*function — defined in `infrastructure.metadata.metadata_package`*

```python
ebook_metadata_from_config(config: dict[str, Any], project_slug: str) -> EbookPublicationMetadata
```

Build ebook metadata from the manuscript config.

### `EbookPublicationMetadata`

*class — defined in `infrastructure.metadata.metadata_package`*

```python
class EbookPublicationMetadata
```

Structured metadata for an ebook / printed publication.

### `generate_epub_opf`

*function — defined in `infrastructure.metadata.metadata_package`*

```python
generate_epub_opf(meta: EbookPublicationMetadata) -> str
```

Generate an EPUB 3.0 OPF (Open Packaging Format) metadata skeleton.

### `generate_metadata_json`

*function — defined in `infrastructure.metadata.metadata_package`*

```python
generate_metadata_json(meta: EbookPublicationMetadata) -> dict[str, Any]
```

Generate a portable ebook metadata dict for retail platform ingestion.

### `generate_metadata_package`

*function — defined in `infrastructure.metadata.metadata_package`*

```python
generate_metadata_package(meta: EbookPublicationMetadata, output_dir: Path) -> dict[str, Path]
```

Generate all three metadata artefacts and write them to *output_dir*.

### `generate_onix_xml`

*function — defined in `infrastructure.metadata.metadata_package`*

```python
generate_onix_xml(meta: EbookPublicationMetadata) -> str
```

Generate an ONIX 3.0 XML string for *meta*.

### `normalized_repository_url`

*function — defined in `infrastructure.metadata.repository_metadata`*

```python
normalized_repository_url(publication: Mapping[str, object] | None) -> str | None
```

Return the explicit repository URL or derive one from ``owner/repo``.

### `repository_metadata`

*symbol — defined in `infrastructure.metadata`*

## Package: `infrastructure.methods`

### `audit_methods_projects`

*function — defined in `infrastructure.methods.orchestration`*

```python
audit_methods_projects(repo_root: Path | str, projects: tuple[str, ...] | list[str], *, artifact_mode: str='rendered', projects_dir: str='projects') -> MethodsAuditReport
```

Build and validate deterministic methods plans for many projects.

### `audit_public_methods`

*function — defined in `infrastructure.methods.orchestration`*

```python
audit_public_methods(repo_root: Path | str, *, artifact_mode: str='rendered') -> MethodsAuditReport
```

Audit the canonical public exemplar roster.

### `build_methods_orchestration_plan`

*function — defined in `infrastructure.methods.orchestration`*

```python
build_methods_orchestration_plan(repo_root: Path | str, project_name: str, *, projects_dir: str='projects', pipeline_path: Path | str | None=None, artifact_mode: str='rendered') -> MethodsOrchestrationPlan
```

Build a deterministic methods orchestration plan for a project.

### `MethodsAuditReport`

*class — defined in `infrastructure.methods.models`*

```python
class MethodsAuditReport
```

Aggregate methods audit across one or more projects.

### `MethodsIssue`

*class — defined in `infrastructure.methods.models`*

```python
class MethodsIssue
```

One methods orchestration validation issue.

### `MethodsOrchestrationPlan`

*class — defined in `infrastructure.methods.models`*

```python
class MethodsOrchestrationPlan
```

Repository-derived methods orchestration plan for one project.

### `MethodsProjectAudit`

*class — defined in `infrastructure.methods.models`*

```python
class MethodsProjectAudit
```

Methods audit result for one project.

### `MethodStage`

*class — defined in `infrastructure.methods.models`*

```python
class MethodStage
```

One pipeline stage viewed as a methods/reproducibility contract.

### `render_methods_orchestration_markdown`

*function — defined in `infrastructure.methods.orchestration`*

```python
render_methods_orchestration_markdown(plan: MethodsOrchestrationPlan) -> str
```

Render a methods orchestration plan as Markdown.

### `validate_methods_orchestration_plan`

*function — defined in `infrastructure.methods.orchestration`*

```python
validate_methods_orchestration_plan(plan: MethodsOrchestrationPlan, *, repo_root: Path | str='.', require_generated_artifacts: bool | None=None) -> tuple[MethodsIssue, ...]
```

Validate methods surfaces and, optionally, generated evidence reports.

## Package: `infrastructure.orchestration`

### `build_parser`

*function — defined in `infrastructure.orchestration.parser`*

```python
build_parser() -> argparse.ArgumentParser
```

Build the compatible top-level orchestration parser.

### `main`

*function — defined in `infrastructure.orchestration.cli`*

```python
main(argv: Sequence[str] | None=None, *, runner_factory: Any=PipelineRunner, secure_runner: Any=run_secure_pipeline, interactive_runner: Any=interactive) -> int
```

Parse, dispatch, and return a stable process exit code.

### `MENU_OPTIONS`

*constant — defined in `infrastructure.orchestration.menu`*

```python
MENU_OPTIONS: tuple[tuple[str, str, str], ...] = (('0', 'Environment Setup', 'stage_00_setup.py'), ('1', 'Run Project Tests', ...
```

### `PipelineRunner`

*class — defined in `infrastructure.orchestration.pipeline_runner`*

```python
class PipelineRunner
```

Thin facade over :class:`PipelineExecutor`.

### `render_menu`

*function — defined in `infrastructure.orchestration.menu`*

```python
render_menu(current_project: str) -> str
```

Return a deterministic menu string for the given current project.

### `run_secure_pipeline`

*function — defined in `infrastructure.orchestration.secure_run`*

```python
run_secure_pipeline(repo_root: Path, options: SecureRunOptions, *, runner_cls: Any=PipelineRunner, processor_factory: Any=None) -> int
```

Run the secure pipeline.

### `select_project_interactive`

*function — defined in `infrastructure.orchestration.discovery`*

```python
select_project_interactive(projects: Sequence[ProjectInfo], *, current: str | None=None, reader: Callable[[], str]=input, writer: TextIO | None=None) -> str | None
```

Interactive project picker.

### `setup_stage_log`

*function — defined in `infrastructure.orchestration.stage_logger`*

```python
setup_stage_log(repo_root: Path, project_name: str, stage_name: str, *, log_name: str=DEFAULT_LOG_NAME, layout: str='per_project', now: datetime | None=None) -> Path
```

Create the log directory and append a session-start banner.

### `validate_project_slug`

*function — defined in `infrastructure.orchestration.discovery`*

```python
validate_project_slug(slug: str, repo_root: Path, *, projects: Sequence[ProjectInfo] | None=None) -> str
```

Validate a user-supplied project slug against discovered projects.

## Package: `infrastructure.project`

### `build_codegraph_files_command`

*symbol — defined in `infrastructure.project`*

### `build_codegraph_init_command`

*symbol — defined in `infrastructure.project`*

### `build_scope_check_command`

*symbol — defined in `infrastructure.project`*

### `CodeGraphCommand`

*symbol — defined in `infrastructure.project`*

### `copy_exemplar`

*symbol — defined in `infrastructure.project`*

### `CopyResult`

*symbol — defined in `infrastructure.project`*

### `discover_import_targets`

*symbol — defined in `infrastructure.project`*

### `discover_projects`

*function — defined in `infrastructure.project.discovery`*

```python
discover_projects(repo_root: Path | str, projects_dir: str='projects') -> list[ProjectInfo]
```

Discover all valid projects in the active projects directory.

### `export_exemplar`

*symbol — defined in `infrastructure.project`*

### `ExportManifest`

*symbol — defined in `infrastructure.project`*

### `find_setup_hook`

*function — defined in `infrastructure.project.setup_hook`*

```python
find_setup_hook(project_dir: Path) -> Path | None
```

Locate the project's setup hook script, if any.

### `get_project_metadata`

*function — defined in `infrastructure.project.metadata`*

```python
get_project_metadata(project_dir: Path) -> dict[str, Any]
```

Extract metadata from project configuration files.

### `load_promotion_attestation`

*symbol — defined in `infrastructure.project`*

### `plan_copy`

*symbol — defined in `infrastructure.project`*

### `preflight_setup_hook`

*function — defined in `infrastructure.project.setup_hook`*

```python
preflight_setup_hook(project_dir: Path, *, strict: bool=False) -> tuple[bool, list[str]]
```

Validate the project's setup-hook prerequisites.

### `ProjectInfo`

*class — defined in `infrastructure.project.project_info`*

```python
class ProjectInfo
```

Information about a discovered project.

### `PromotionAttestation`

*symbol — defined in `infrastructure.project`*

### `public_ci_lint_paths`

*symbol — defined in `infrastructure.project`*

### `public_ci_source_paths`

*symbol — defined in `infrastructure.project`*

### `public_project_infos`

*symbol — defined in `infrastructure.project`*

### `PUBLIC_PROJECT_NAMES`

*symbol — defined in `infrastructure.project`*

### `public_project_names`

*symbol — defined in `infrastructure.project`*

### `resolve_project_root`

*function — defined in `infrastructure.core.project_paths`*

```python
resolve_project_root(repo_root: Path | str, project_name: str) -> Path
```

Return the directory for *project_name*, preferring the hot seat over WIP trees.

### `run_project_setup_hook`

*function — defined in `infrastructure.project.setup_hook`*

```python
run_project_setup_hook(project_dir: Path) -> bool
```

Run the project's setup hook, if present.

### `validate_project_structure`

*function — defined in `infrastructure.project.validation`*

```python
validate_project_structure(project_dir: Path) -> tuple[bool, str]
```

Validate that project has required directory structure.

### `validate_promotion_attestation`

*symbol — defined in `infrastructure.project`*

### `verify_codegraph_scope_payload`

*symbol — defined in `infrastructure.project`*

## Package: `infrastructure.prose`

### `analyze_files`

*function — defined in `infrastructure.prose.report`*

```python
analyze_files(files: Mapping[str, str], *, long_sentence_threshold: int=35) -> ManuscriptReport
```

Build a :class:`ManuscriptReport` from a ``{filename: text}`` mapping.

### `analyze_manuscript`

*function — defined in `infrastructure.prose.report`*

```python
analyze_manuscript(manuscript_dir: Path | str, *, long_sentence_threshold: int=35) -> ManuscriptReport
```

Read every Markdown file in *manuscript_dir* and analyse it.

### `analyze_quality`

*function — defined in `infrastructure.prose.analysis.quality`*

```python
analyze_quality(text: str, *, long_sentence_threshold: int=35) -> QualityReport
```

Run every detector over *text* and return a :class:`QualityReport`.

### `analyze_structure`

*function — defined in `infrastructure.prose.analysis.structure`*

```python
analyze_structure(markdown: str) -> StructureReport
```

Build a :class:`StructureReport` for *markdown*.

### `analyze_text`

*function — defined in `infrastructure.prose.report`*

```python
analyze_text(name: str, raw_text: str, *, long_sentence_threshold: int=35) -> FileReport
```

Analyze a single text blob and return a :class:`FileReport`.

### `compute_metrics`

*function — defined in `infrastructure.prose.analysis.metrics`*

```python
compute_metrics(text: str) -> ProseMetrics
```

Compute :class:`ProseMetrics` for *text*.

### `count_syllables`

*function — defined in `infrastructure.prose.analysis.metrics`*

```python
count_syllables(word: str) -> int
```

Estimate syllables in *word* using vowel-group heuristic.

### `detect_hedge_words`

*function — defined in `infrastructure.prose.analysis.quality`*

```python
detect_hedge_words(text: str) -> list[str]
```

Return list of hedge words present in *text* (with duplicates).

### `detect_long_sentences`

*function — defined in `infrastructure.prose.analysis.quality`*

```python
detect_long_sentences(text: str, *, threshold: int=35) -> list[str]
```

Return sentences with > *threshold* words.

### `detect_passive_sentences`

*function — defined in `infrastructure.prose.analysis.quality`*

```python
detect_passive_sentences(text: str) -> list[str]
```

Return sentences with at least one "be + past participle" pair.

### `extract_citation_keys`

*function — defined in `infrastructure.prose.analysis.quality`*

```python
extract_citation_keys(text: str) -> list[str]
```

Extract Pandoc-style ``@key`` citations from *text*.

### `FileReport`

*class — defined in `infrastructure.prose.report`*

```python
class FileReport
```

Per-file prose report.

### `Heading`

*class — defined in `infrastructure.prose.analysis.structure`*

```python
class Heading
```

One heading in a Markdown document.

### `is_complex_word`

*function — defined in `infrastructure.prose.analysis.metrics`*

```python
is_complex_word(word: str) -> bool
```

A "complex word" for Gunning Fog: ≥3 syllables, not proper noun,

### `load_report_json`

*function — defined in `infrastructure.prose.report`*

```python
load_report_json(path: Path | str) -> ManuscriptReport
```

Load a :class:`ManuscriptReport` from on-disk JSON.

### `ManuscriptReport`

*class — defined in `infrastructure.prose.report`*

```python
class ManuscriptReport
```

Aggregate report for an entire manuscript directory.

### `normalise_for_prose`

*function — defined in `infrastructure.prose.markdown`*

```python
normalise_for_prose(text: str) -> str
```

Apply all stripping passes in canonical order.

### `parse_headings`

*function — defined in `infrastructure.prose.analysis.structure`*

```python
parse_headings(markdown: str) -> list[Heading]
```

Extract ATX (#-style) headings from *markdown*, ignoring code fences.

### `ProseMetrics`

*class — defined in `infrastructure.prose.analysis.metrics`*

```python
class ProseMetrics
```

Container for prose metrics.

### `QualityReport`

*class — defined in `infrastructure.prose.analysis.quality`*

```python
class QualityReport
```

Aggregate quality flags.

### `read_manuscript_dir`

*function — defined in `infrastructure.prose.markdown`*

```python
read_manuscript_dir(manuscript_dir: Path | str, *, include: str='*.md', exclude_filenames: tuple[str, ...]=('preamble.md', 'config.yaml.example', 'AGENTS.md', 'README.md', 'SYNTAX.md')) -> dict[str, str]
```

Read every Markdown file in *manuscript_dir* into a ``{name: text}`` map.

### `render_outline`

*function — defined in `infrastructure.prose.analysis.structure`*

```python
render_outline(report: StructureReport) -> str
```

Render *report* as a plain-text bulleted outline.

### `Section`

*class — defined in `infrastructure.prose.analysis.structure`*

```python
class Section
```

A heading together with the body text up to the next same-or-shallower heading.

### `split_paragraphs`

*function — defined in `infrastructure.prose.analysis.metrics`*

```python
split_paragraphs(text: str) -> list[str]
```

Split *text* on blank lines into non-empty paragraphs.

### `split_sentences`

*function — defined in `infrastructure.prose.analysis.metrics`*

```python
split_sentences(text: str) -> list[str]
```

Split *text* into sentences using a conservative heuristic.

### `strip_fences`

*function — defined in `infrastructure.prose.markdown`*

```python
strip_fences(text: str) -> str
```

Remove fenced code blocks (``` ... ```).

### `strip_front_matter`

*function — defined in `infrastructure.prose.markdown`*

```python
strip_front_matter(text: str) -> str
```

Remove a leading YAML front-matter block, if any.

### `strip_inline_code`

*function — defined in `infrastructure.prose.markdown`*

```python
strip_inline_code(text: str) -> str
```

Remove inline code spans (`...`).

### `strip_links_to_text`

*function — defined in `infrastructure.prose.markdown`*

```python
strip_links_to_text(text: str) -> str
```

Replace ``[label](url)`` with ``label`` and drop ``![alt](url)``.

### `StructureReport`

*class — defined in `infrastructure.prose.analysis.structure`*

```python
class StructureReport
```

Outline of a Markdown document, with per-section word counts.

### `tokenize_words`

*function — defined in `infrastructure.prose.analysis.metrics`*

```python
tokenize_words(text: str) -> list[str]
```

Return the list of word tokens in *text*.

### `write_report`

*function — defined in `infrastructure.prose.report`*

```python
write_report(report: ManuscriptReport, output_path: Path | str) -> Path
```

Persist *report* as pretty-printed JSON.

## Package: `infrastructure.provenance`

### `ArtifactNode`

*class — defined in `infrastructure.provenance.models`*

```python
class ArtifactNode(NodeBase)
```

Provenance node for a file or dataset artifact.

### `ClaimNode`

*class — defined in `infrastructure.provenance.models`*

```python
class ClaimNode(NodeBase)
```

Provenance node for a scientific claim or assertion.

### `Edge`

*class — defined in `infrastructure.provenance.models`*

```python
class Edge
```

A directed edge between two provenance nodes.

### `EdgeRelation`

*class — defined in `infrastructure.provenance.models`*

```python
class EdgeRelation(str, Enum)
```

Directed relationship type between two provenance nodes.

### `ExperimentCode`

*class — defined in `infrastructure.provenance.tree`*

```python
class ExperimentCode
```

Stable dotted diagnostic IDs for experiment-tree findings.

### `ExperimentKind`

*class — defined in `infrastructure.provenance.tree`*

```python
class ExperimentKind(str, Enum)
```

Role of an experiment node within its tree.

### `ExperimentNode`

*class — defined in `infrastructure.provenance.tree`*

```python
class ExperimentNode
```

A node in an experiment tree, persisted in the provenance store.

### `ExperimentStatus`

*class — defined in `infrastructure.provenance.tree`*

```python
class ExperimentStatus(str, Enum)
```

Lifecycle status of an experiment node.

### `ExperimentTree`

*class — defined in `infrastructure.provenance.tree`*

```python
class ExperimentTree(store: Provenance)
```

Experiment-tree discipline layered on an existing :class:`Provenance` store.

### `Finding`

*class — defined in `infrastructure.provenance.review`*

```python
class Finding
```

A single review finding attached to a provenance node.

### `load_provenance_config`

*function — defined in `infrastructure.provenance.config`*

```python
load_provenance_config(project_dir: Path | str, *, yaml_importer: Callable[[str], Any]=import_module) -> ProvenanceConfig
```

Load optional ``provenance.yaml`` from *project_dir*.

### `node_from_dict`

*function — defined in `infrastructure.provenance.models`*

```python
node_from_dict(data: dict[str, Any]) -> ProvenanceNode
```

Deserialise a node from a plain dictionary.

### `NodeKind`

*class — defined in `infrastructure.provenance.models`*

```python
class NodeKind(str, Enum)
```

Classification of a provenance node.

### `Provenance`

*class — defined in `infrastructure.provenance.store`*

```python
class Provenance(path: Path)
```

Persistent provenance DAG store.

### `ProvenanceConfig`

*class — defined in `infrastructure.provenance.config`*

```python
class ProvenanceConfig
```

Runtime configuration for the provenance DAG.

### `ProvenanceNode`

*constant — defined in `infrastructure.provenance.models`*

```python
ProvenanceNode = ArtifactNode | RunNode | SourceNode | ClaimNode
```

### `ProvenanceStoreError`

*class — defined in `infrastructure.provenance.store`*

```python
class ProvenanceStoreError(ValueError)
```

Raised when a provenance store is malformed or cannot be read.

### `ProvenanceValidationFinding`

*class — defined in `infrastructure.provenance.validation`*

```python
class ProvenanceValidationFinding
```

A single issue discovered during provenance DAG validation.

### `ProvenanceValidationReport`

*class — defined in `infrastructure.provenance.validation`*

```python
class ProvenanceValidationReport
```

Report detailing DAG structural and content integrity.

### `Review`

*class — defined in `infrastructure.provenance.review`*

```python
class Review()
```

Accumulator for provenance review findings.

### `review_provenance_store`

*function — defined in `infrastructure.provenance.review`*

```python
review_provenance_store(store: Any) -> ReviewResult
```

Run a standard review pass over a :class:`~Provenance` store.

### `ReviewResult`

*class — defined in `infrastructure.provenance.review`*

```python
class ReviewResult
```

Aggregated result of a review pass.

### `RunNode`

*class — defined in `infrastructure.provenance.models`*

```python
class RunNode(NodeBase)
```

Provenance node for a pipeline run or script execution.

### `Severity`

*class — defined in `infrastructure.provenance.review`*

```python
class Severity(str, Enum)
```

Severity level for a review finding.

### `SourceNode`

*class — defined in `infrastructure.provenance.models`*

```python
class SourceNode(NodeBase)
```

Provenance node for an external data source or reference.

### `validate_experiment_tree`

*function — defined in `infrastructure.provenance.tree`*

```python
validate_experiment_tree(tree: ExperimentTree) -> ProvenanceValidationReport
```

Validate tree discipline: fixed run contract, acyclicity, single baseline.

### `validate_provenance_dag`

*function — defined in `infrastructure.provenance.validation`*

```python
validate_provenance_dag(store: Provenance) -> ProvenanceValidationReport
```

Validate graph structure, references, and acyclicity of a Provenance store.

## Package: `infrastructure.publishing`

### `ArchivalProvider`

*class — defined in `infrastructure.publishing.archival.providers`*

```python
class ArchivalProvider(Protocol)
```

Protocol every archival provider must implement.

### `ArchivalReceipt`

*class — defined in `infrastructure.publishing.archival.models`*

```python
class ArchivalReceipt
```

Structured record of a single archival deposit attempt.

### `ArchivalRun`

*class — defined in `infrastructure.publishing.archival.models`*

```python
class ArchivalRun
```

Aggregate result of an ``archive_publication`` call.

### `archive_publication`

*function — defined in `infrastructure.publishing.archival.orchestrate`*

```python
archive_publication(bundle: Path, *, providers: list[ArchivalProvider], dry_run: bool=True, output_receipts_path: Path | None=None, repo_root: Path | None=None, project_name: str | None=None, credential_sources: Mapping[str, str] | None=None) -> ArchivalRun
```

Mirror a publication bundle to N independent archival targets.

### `build_coverage_gap_snapshot`

*function — defined in `infrastructure.publishing.release.release_receipts`*

```python
build_coverage_gap_snapshot(*, revision: str, infrastructure_percent: float | None, infrastructure_floor: float, projects: Mapping[str, float | None], project_floors: Mapping[str, float]) -> CoverageGapSnapshot
```

Build a coverage receipt without coercing unavailable values to zero.

### `build_release_metadata_receipt`

*function — defined in `infrastructure.publishing.release.release_receipts`*

```python
build_release_metadata_receipt(*, repository: str, revision: str, version: str, command: tuple[str, ...], scope: tuple[str, ...], owner: str, checked_at: str, health: str, verification_mode: VerificationMode='offline', source_urls: tuple[str, ...]=(), artifact: str='', branch_protection: AuthorityStatus='unavailable', private_promotion: AuthorityStatus='unavailable', status: ReceiptStatus='review_required', skip_reason: str='') -> ReleaseMetadataReceipt
```

Build a metadata receipt with all reproducibility fields explicit.

### `build_subprocess_policy_receipt`

*function — defined in `infrastructure.publishing.release.release_receipts`*

```python
build_subprocess_policy_receipt(repo_root: Path | str | None=None, *, policies: Sequence[SubprocessPolicy]=INTENTIONAL_SUBPROCESS_POLICIES) -> SubprocessPolicyReceipt
```

Build a receipt from the source-owned intentional-wrapper inventory.

### `calculate_metadata_complexity_score`

*function — defined in `infrastructure.publishing._metadata_reporting`*

```python
calculate_metadata_complexity_score(metadata: PublicationMetadata) -> int
```

Calculate a complexity score for the publication.

### `CitationStyle`

*class — defined in `infrastructure.publishing.models`*

```python
class CitationStyle
```

Container for citation style configuration.

### `CleanCheckoutReceipt`

*class — defined in `infrastructure.publishing.release.release_receipts`*

```python
class CleanCheckoutReceipt
```

Fresh-checkout rehearsal result with explicit unavailable-tool states.

### `CloudflarePagesAdapter`

*class — defined in `infrastructure.publishing.static_site.cloudflare_pages`*

```python
class CloudflarePagesAdapter(config: SiteDeployConfig)
```

Data container for CloudflarePagesAdapter.

### `CommandReceipt`

*class — defined in `infrastructure.publishing.release.release_receipts`*

```python
class CommandReceipt
```

Evidence for one command without recording secret environment values.

### `CoverageGapSnapshot`

*class — defined in `infrastructure.publishing.release.release_receipts`*

```python
class CoverageGapSnapshot
```

Source-bound coverage-floor snapshot for release review.

### `create_academic_profile_data`

*function — defined in `infrastructure.publishing._metadata_reporting`*

```python
create_academic_profile_data(metadata: PublicationMetadata) -> dict[str, Any]
```

Create academic profile data for ORCID, ResearchGate, etc.

### `create_github_release`

*function — defined in `infrastructure.publishing.github.release`*

```python
create_github_release(tag_name: str, release_name: str, description: str, assets: list[Path], token: str, repo: str, *, base_url: str='https://api.github.com', target_commitish: str='main', requests_available: bool=_requests_available) -> str
```

Create a GitHub release with attached assets.

### `create_publication_announcement`

*function — defined in `infrastructure.publishing.announcement`*

```python
create_publication_announcement(metadata: PublicationMetadata) -> str
```

Create a publication announcement for social media and blogs.

### `create_publication_package`

*function — defined in `infrastructure.publishing.package`*

```python
create_publication_package(output_dir: Path, metadata: PublicationMetadata) -> dict[str, Any]
```

Create a publication package with all necessary files.

### `create_repository_metadata`

*function — defined in `infrastructure.publishing._metadata_reporting`*

```python
create_repository_metadata(metadata: PublicationMetadata) -> str
```

Create repository metadata JSON for GitHub/GitLab.

### `create_submission_checklist`

*function — defined in `infrastructure.publishing.checklist`*

```python
create_submission_checklist(metadata: PublicationMetadata) -> str
```

Create a submission checklist for academic conferences/journals.

### `documented_platforms`

*function — defined in `infrastructure.publishing.registry`*

```python
documented_platforms() -> tuple[PlatformInfo, ...]
```

Return only documented (future) platforms.

### `extract_citations_from_markdown`

*function — defined in `infrastructure.publishing.citations`*

```python
extract_citations_from_markdown(markdown_files: list[Path]) -> list[str]
```

Extract all citations from markdown files.

### `extract_publication_metadata`

*function — defined in `infrastructure.publishing._metadata_extraction`*

```python
extract_publication_metadata(markdown_files: list[Path]) -> PublicationMetadata
```

Extract publication metadata from markdown files.

### `first_class_platforms`

*function — defined in `infrastructure.publishing.registry`*

```python
first_class_platforms() -> tuple[PlatformInfo, ...]
```

Return only first-class (implemented) platforms.

### `generate_citation_apa`

*function — defined in `infrastructure.publishing.citations`*

```python
generate_citation_apa(metadata: PublicationMetadata) -> str
```

Generate APA citation format.

### `generate_citation_bibtex`

*function — defined in `infrastructure.publishing.citations`*

```python
generate_citation_bibtex(metadata: PublicationMetadata) -> str
```

Generate BibTeX citation format.

### `generate_citation_mla`

*function — defined in `infrastructure.publishing.citations`*

```python
generate_citation_mla(metadata: PublicationMetadata) -> str
```

Generate MLA citation format.

### `generate_citations_markdown`

*function — defined in `infrastructure.publishing.citations`*

```python
generate_citations_markdown(metadata: PublicationMetadata) -> str
```

Generate markdown section with all citation formats.

### `generate_doi_badge`

*function — defined in `infrastructure.publishing.announcement`*

```python
generate_doi_badge(doi: str, style: str='zenodo') -> str
```

Generate DOI badge markdown.

### `generate_publication_metrics`

*function — defined in `infrastructure.publishing._metadata_reporting`*

```python
generate_publication_metrics(metadata: PublicationMetadata) -> dict[str, Any]
```

Generate publication metrics for reporting.

### `generate_publication_summary`

*function — defined in `infrastructure.publishing._metadata_reporting`*

```python
generate_publication_summary(metadata: PublicationMetadata) -> str
```

Generate a publication summary for repository README.

### `get_platform`

*function — defined in `infrastructure.publishing.registry`*

```python
get_platform(name: str) -> PlatformInfo
```

Return PlatformInfo by name. Raises KeyError if not found.

### `get_static_site_adapter`

*symbol — defined in `infrastructure.publishing.static_site`*

### `GitHubPagesAdapter`

*class — defined in `infrastructure.publishing.static_site.github_pages`*

```python
class GitHubPagesAdapter(config: SiteDeployConfig)
```

Deploy a site using explicit credentials and a validated destination.

### `list_platforms`

*function — defined in `infrastructure.publishing.registry`*

```python
list_platforms(*, tier: PublishingTier | None=None, tag: str | None=None) -> tuple[PlatformInfo, ...]
```

Return platforms, optionally filtered by tier or tag.

### `load_credentials`

*function — defined in `infrastructure.publishing.archival.orchestrate`*

```python
load_credentials(*, env: dict[str, str] | None=None, credentials_path: Path | None=None) -> ArchivalCredentials
```

Read provider credentials from env vars first, then a JSON file.

### `NetlifyAdapter`

*class — defined in `infrastructure.publishing.static_site.netlify`*

```python
class NetlifyAdapter(config: SiteDeployConfig)
```

Data container for NetlifyAdapter.

### `PLATFORM_REGISTRY`

*constant — defined in `infrastructure.publishing.registry`*

```python
PLATFORM_REGISTRY: tuple[PlatformInfo, ...] = (PlatformInfo(name='zenodo', tier=PublishingTier.FIRST_CLASS, description='CE...
```

### `PlatformInfo`

*class — defined in `infrastructure.publishing.registry`*

```python
class PlatformInfo
```

Metadata about a publishing platform adapter.

### `prepare_arxiv_submission`

*function — defined in `infrastructure.publishing.arxiv.submission`*

```python
prepare_arxiv_submission(output_dir: Path, metadata: PublicationMetadata) -> Path
```

Build a deterministic, non-partial LaTeX-source package for manual upload.

### `PublicationMetadata`

*class — defined in `infrastructure.publishing.models`*

```python
class PublicationMetadata
```

Container for publication metadata.

### `publish_to_zenodo`

*function — defined in `infrastructure.publishing.zenodo.publish`*

```python
publish_to_zenodo(metadata: PublicationMetadata, file_paths: list[Path], access_token: str, sandbox: bool=True, *, base_url: str | None=None) -> PublishResult
```

Publish research artifacts to Zenodo and return DOI plus deposition id.

### `PublishingTier`

*class — defined in `infrastructure.publishing.registry`*

```python
class PublishingTier(str, Enum)
```

Data container for PublishingTier.

### `PyPIAdapter`

*class — defined in `infrastructure.publishing.pypi.adapter`*

```python
class PyPIAdapter(config: PyPIConfig | None=None, *, env: dict[str, str] | None=None)
```

Public operating adapter with bounded, source-bound platform admission.

### `ReleaseMetadataReceipt`

*class — defined in `infrastructure.publishing.release.release_receipts`*

```python
class ReleaseMetadataReceipt
```

Release status plus explicit administrator-owned authority fields.

### `SiteDeployConfig`

*class — defined in `infrastructure.publishing.static_site.models`*

```python
class SiteDeployConfig
```

Configuration for a static-site deployment.

### `SiteDeployResult`

*class — defined in `infrastructure.publishing.static_site.models`*

```python
class SiteDeployResult
```

Result of a static-site deploy attempt.

### `SiteHosting`

*class — defined in `infrastructure.publishing.static_site.models`*

```python
class SiteHosting(str, Enum)
```

Data container for SiteHosting.

### `SubprocessPolicyReceipt`

*class — defined in `infrastructure.publishing.release.release_receipts`*

```python
class SubprocessPolicyReceipt
```

Versioned inventory of intentional subprocess wrappers.

### `validate_doi`

*function — defined in `infrastructure.publishing._metadata_extraction`*

```python
validate_doi(doi: str) -> bool
```

Validate DOI format and checksum.

### `validate_publication_readiness`

*function — defined in `infrastructure.publishing.readiness`*

```python
validate_publication_readiness(markdown_files: list[Path], pdf_files: list[Path]) -> dict[str, Any]
```

Validate that the project is ready for publication.

### `ZenodoClient`

*class — defined in `infrastructure.publishing.zenodo.client`*

```python
class ZenodoClient(config: ZenodoConfig, *, requests_available: bool=_requests_available)
```

Client for the Zenodo Deposit REST API.

### `ZenodoConfig`

*class — defined in `infrastructure.publishing.zenodo.config`*

```python
class ZenodoConfig
```

Configuration for Zenodo API client.

## Package: `infrastructure.reference`

### `BibDatabase`

*class — defined in `infrastructure.reference.citation.models`*

```python
class BibDatabase
```

A collection of :class:`BibEntry` records preserving insertion order.

### `BibEntry`

*class — defined in `infrastructure.reference.citation.models`*

```python
class BibEntry
```

A single BibTeX record.

### `BibParseError`

*class — defined in `infrastructure.reference.citation.bibtex_parser`*

```python
class BibParseError(ValueError)
```

Raised when the parser encounters a malformed BibTeX construct.

### `generate_citation_key`

*function — defined in `infrastructure.reference.citation.converter`*

```python
generate_citation_key(*, authors: list[str], year: int | str | None, title: str, fallback: str='anon') -> str
```

Build a citation key in the project's house style.

### `paper_to_bibentry`

*function — defined in `infrastructure.reference.citation.converter`*

```python
paper_to_bibentry(paper: 'Paper', *, citation_key: str | None=None, entry_type: str | None=None) -> BibEntry
```

Convert a :class:`Paper` record into a :class:`BibEntry`.

### `parse_bibfile`

*function — defined in `infrastructure.reference.citation.bibtex_parser`*

```python
parse_bibfile(path: Path | str, *, encoding: str='utf-8') -> BibDatabase
```

Read and parse a ``.bib`` file from *path*.

### `parse_bibtex`

*function — defined in `infrastructure.reference.citation.bibtex_parser`*

```python
parse_bibtex(text: str) -> BibDatabase
```

Parse *text* into a :class:`BibDatabase`.

### `render_database`

*function — defined in `infrastructure.reference.citation.bibtex_writer`*

```python
render_database(database: BibDatabase) -> str
```

Render an entire :class:`BibDatabase` to a BibTeX string.

### `render_entry`

*function — defined in `infrastructure.reference.citation.bibtex_writer`*

```python
render_entry(entry: BibEntry) -> str
```

Render a single :class:`BibEntry` to a BibTeX string.

### `write_bibfile`

*function — defined in `infrastructure.reference.citation.bibtex_writer`*

```python
write_bibfile(path: Path | str, database: BibDatabase, *, encoding: str='utf-8') -> Path
```

Render *database* and write it to *path*.

## Package: `infrastructure.rendering`

### `discover_manuscript_files`

*function — defined in `infrastructure.rendering.manuscript_discovery`*

```python
discover_manuscript_files(manuscript_dir: Path) -> list[Path]
```

Discover manuscript files with proper ordering and filtering.

### `DocxRenderResult`

*class — defined in `infrastructure.rendering.docx_renderer`*

```python
class DocxRenderResult
```

Outcome of a DOCX render.

### `EpubRenderResult`

*class — defined in `infrastructure.rendering.epub_renderer`*

```python
class EpubRenderResult
```

Outcome of an EPUB render.

### `EXCLUDED_DOC_FILENAMES`

*constant — defined in `infrastructure.rendering.manuscript_injection`*

```python
EXCLUDED_DOC_FILENAMES: frozenset[str] = frozenset({'AGENTS.md', 'MANUSCRIPT_STATUS.md', 'README.md', 'SYNTAX.md'})
```

### `export_project`

*function — defined in `infrastructure.rendering.docxplus_export`*

```python
export_project(project_root: Path, output_dir: Path, *, project: str, title: str | None=None, author: str | None=None, signing_key_hex: str | None=None, password: str | None=None) -> ExportResult
```

Write ``<project>.docx`` and ``<project>.docxplus`` carrying ``project_root``.

### `ExportResult`

*class — defined in `infrastructure.rendering.docxplus_export`*

```python
class ExportResult
```

What the export produced, or why it produced nothing.

### `is_docxplus_available`

*symbol — defined in `infrastructure.rendering.docxplus_export`*

### `ManuscriptRenderCache`

*class — defined in `infrastructure.rendering.render_cache`*

```python
class ManuscriptRenderCache(cache_file: Path | str)
```

File-backed incremental rendering cache.

### `render_docx`

*function — defined in `infrastructure.rendering.docx_renderer`*

```python
render_docx(combined_md: Path, output_path: Path, *, bibliography: Path | None=None, reference_doc: Path | None=None, title: str | None=None, author: str | None=None, pandoc_path: str='pandoc', extra_args: list[str] | None=None, diagram_png_sha256: tuple[str, ...]=()) -> DocxRenderResult
```

Render *combined_md* to a DOCX at *output_path*.

### `render_epub`

*function — defined in `infrastructure.rendering.epub_renderer`*

```python
render_epub(combined_md: Path, output_path: Path, *, bibliography: Path | None=None, cover_image: Path | None=None, cover_alt: str | None=None, title: str | None=None, author: str | None=None, language: str='en', pandoc_path: str='pandoc', extra_args: list[str] | None=None) -> EpubRenderResult
```

Render *combined_md* to an EPUB at *output_path*.

### `RenderCacheError`

*class — defined in `infrastructure.rendering.render_cache`*

```python
class RenderCacheError(ValueError)
```

Raised when the persistent render cache cannot be trusted or saved.

### `RenderingConfig`

*class — defined in `infrastructure.rendering.config`*

```python
class RenderingConfig
```

Configuration for rendering output.

### `RenderManager`

*class — defined in `infrastructure.rendering.core`*

```python
class RenderManager(config: RenderingConfig | None=None, manuscript_dir: Path | None=None, figures_dir: Path | None=None, *, slides_renderer: Any=None, web_renderer: Any=None)
```

Orchestrates rendering of all output formats.

### `run_docxplus_export`

*function — defined in `infrastructure.rendering.docxplus_stage`*

```python
run_docxplus_export(repo_root: Path, project: str, *, signing_key_path: str | None=None, password: str | None=None) -> int
```

Execute the docxplus export for ``project``. Returns a process exit code.

### `SectionCacheEntry`

*class — defined in `infrastructure.rendering.render_cache`*

```python
class SectionCacheEntry
```

Cache record for a single rendered manuscript section.

### `substitute_manuscript_text`

*function — defined in `infrastructure.rendering.manuscript_injection`*

```python
substitute_manuscript_text(text: str, variables: dict[str, str]) -> tuple[str, list[str]]
```

Replace ``{{KEY}}`` placeholders in *text* with values from *variables*.

### `verify_figures_exist`

*function — defined in `infrastructure.rendering.manuscript_discovery`*

```python
verify_figures_exist(project_root: Path, manuscript_dir: Path) -> dict[str, Any]
```

Verify expected figures exist, return status.

### `write_resolved_manuscript_tree`

*function — defined in `infrastructure.rendering.manuscript_injection`*

```python
write_resolved_manuscript_tree(project_root: Path | str, variables: dict[str, str]) -> Path
```

Write resolved copies of ``manuscript/*.md`` into ``output/manuscript/``.

## Package: `infrastructure.reporting`

### `collect_output_statistics`

*function — defined in `infrastructure.reporting.output_statistics`*

```python
collect_output_statistics(repo_root: Path, project_name: str='project', project_dir: Path | None=None, *, require_pdf: bool=True, output_dir: Path | None=None, inventory: StableOutputInventory | None=None, enabled_formats: Collection[str] | None=None, inventory_scope: str=PROJECT_OUTPUT_INVENTORY_SCOPE, inventory_mode: OutputInventoryMode=STABLE_OUTPUT_INVENTORY_MODE) -> dict[str, Any]
```

Collect comprehensive output file statistics.

### `collect_project_metrics`

*function — defined in `infrastructure.reporting._executive_collectors`*

```python
collect_project_metrics(repo_root: Path, project_name: str, project_dir: Path | None=None) -> ProjectMetrics
```

Collect all metrics for a single project.

### `Control`

*class — defined in `infrastructure.reporting._interactive_models`*

```python
class Control
```

One interactive control (slider / dropdown / toggle).

### `DASHBOARD_AVAILABLE`

*symbol — defined in `infrastructure.reporting`*

### `ErrorAggregator`

*class — defined in `infrastructure.reporting.error_aggregator`*

```python
class ErrorAggregator()
```

Aggregate and categorize errors from pipeline execution.

### `ErrorEntry`

*class — defined in `infrastructure.reporting.error_aggregator`*

```python
class ErrorEntry
```

Single error or warning entry.

### `ExecutiveSummary`

*class — defined in `infrastructure.reporting._executive_models`*

```python
class ExecutiveSummary
```

Executive summary aggregating all project metrics.

### `FileType`

*class — defined in `infrastructure.reporting.output_organizer`*

```python
class FileType(Enum)
```

Enumeration of supported file types for output organization.

### `generate_executive_summary`

*function — defined in `infrastructure.reporting._executive_renderers`*

```python
generate_executive_summary(repo_root: Path, project_names: list[str]) -> ExecutiveSummary
```

Generate complete executive summary for all projects.

### `generate_markdown_report`

*function — defined in `infrastructure.reporting.markdown_formatter`*

```python
generate_markdown_report(data: dict[str, Any]) -> str
```

Generate human-readable markdown report from test data.

### `generate_multi_project_report`

*function — defined in `infrastructure.reporting.multi_project_reporter`*

```python
generate_multi_project_report(repo_root: Path, project_names: list[str], output_dir: Path) -> dict[str, Path]
```

Orchestrate executive reporting for multiple projects into output_dir.

### `generate_multi_project_summary_report`

*function — defined in `infrastructure.reporting.multi_project_reporter`*

```python
generate_multi_project_summary_report(result: MultiProjectResult, projects: list[Any], output_dir: Path) -> dict[str, Path]
```

Generate comprehensive multi-project summary report.

### `generate_pipeline_report`

*function — defined in `infrastructure.reporting.pipeline_report_model`*

```python
generate_pipeline_report(stage_results: list[_StageResultDict], total_duration: float, repo_root: Path, *, test_results: dict[str, Any] | None=None, validation_results: dict[str, Any] | None=None, performance_metrics: dict[str, Any] | None=None, error_summary: dict[str, Any] | None=None, output_statistics: dict[str, Any] | None=None, project_name: str | None=None, project_dir: Path | None=None) -> PipelineReport
```

Generate consolidated pipeline report from stage results and optional extras.

### `generate_summary_report`

*function — defined in `infrastructure.reporting.report_builder`*

```python
generate_summary_report(repo_root: Path | None=None) -> dict[str, Any]
```

Generate the test summary report.

### `get_error_aggregator`

*function — defined in `infrastructure.reporting.error_aggregator`*

```python
get_error_aggregator() -> 'ErrorAggregator'
```

Get global error aggregator instance (lazily initialized).

### `InteractiveDashboard`

*class — defined in `infrastructure.reporting.interactive_dashboard`*

```python
class InteractiveDashboard(title: str, subtitle: str='', project_name: str='', repo_root: Path | None=None)
```

Build a single self-contained interactive simulation dashboard.

### `Invariant`

*class — defined in `infrastructure.reporting._interactive_models`*

```python
class Invariant
```

A single numerical invariant to validate.

### `load_infrastructure_results`

*function — defined in `infrastructure.reporting.result_loaders`*

```python
load_infrastructure_results(repo_root: Path | None=None) -> InfraResults
```

Load infrastructure test results from root coverage files.

### `load_test_results`

*function — defined in `infrastructure.reporting.result_loaders`*

```python
load_test_results(project_name: str, repo_root: Path | None=None, project_dir: Path | None=None) -> dict[str, Any]
```

Load test results from a project's output directory; returns {} if not found.

### `log_output_summary`

*function — defined in `infrastructure.reporting.output_statistics`*

```python
log_output_summary(output_dir: Path, stats: dict[str, Any], structure_validation: Mapping[str, Any] | None=None) -> None
```

Generate summary of output copying results.

### `OutputOrganizer`

*class — defined in `infrastructure.reporting.output_organizer`*

```python
class OutputOrganizer
```

Centralized organizer for executive summary and multi-project outputs.

### `Panel`

*class — defined in `infrastructure.reporting._interactive_models`*

```python
class Panel
```

One Plotly figure on the dashboard.

### `ProjectMetrics`

*class — defined in `infrastructure.reporting._executive_models`*

```python
class ProjectMetrics
```

Complete metrics for a single project.

### `reset_error_aggregator`

*function — defined in `infrastructure.reporting.error_aggregator`*

```python
reset_error_aggregator() -> None
```

Reset global error aggregator (for testing).

### `run_test_summary_generation`

*function — defined in `infrastructure.reporting.markdown_formatter`*

```python
run_test_summary_generation() -> int
```

Main entry point for generating test summary reports.

### `save_error_summary`

*function — defined in `infrastructure.reporting.pipeline_io`*

```python
save_error_summary(errors: list[dict[str, Any]], output_dir: Path) -> dict[str, Any]
```

Aggregate errors, write JSON and Markdown reports, and return the summary dict.

### `save_executive_summary`

*function — defined in `infrastructure.reporting._executive_renderers`*

```python
save_executive_summary(summary: ExecutiveSummary, output_dir: Path) -> dict[str, Path]
```

Save executive summary in multiple formats.

### `save_performance_report`

*function — defined in `infrastructure.reporting.pipeline_io`*

```python
save_performance_report(performance_metrics: dict[str, Any], output_dir: Path) -> Path
```

Write performance_metrics dict to performance_report.json and return the path.

### `save_pipeline_report`

*function — defined in `infrastructure.reporting.pipeline_io`*

```python
save_pipeline_report(report: PipelineReport, output_dir: Path, formats: list[str] | None=None) -> dict[str, Path]
```

Save pipeline report in multiple formats; returns dict mapping format to path.

### `save_test_results`

*function — defined in `infrastructure.reporting.pipeline_io`*

```python
save_test_results(test_results: dict[str, Any], output_dir: Path) -> Path
```

Write test_results dict to test_results.json and return the path.

### `save_validation_report`

*function — defined in `infrastructure.reporting.pipeline_io`*

```python
save_validation_report(validation_results: dict[str, Any], output_dir: Path) -> dict[str, Path]
```

Generate validation report as JSON and Markdown; returns paths by format key.

### `write_output_statistics_reports`

*function — defined in `infrastructure.reporting.output_statistics`*

```python
write_output_statistics_reports(project_output_dir: Path, stats: dict[str, Any], *, report_output_dir: Path | None=None) -> tuple[Path, Path]
```

Write text and JSON output statistics reports under ``output/reports``.

## Package: `infrastructure.research`

### `load_research_workflow_config`

*function — defined in `infrastructure.research.config`*

```python
load_research_workflow_config(project_dir: Path | str) -> ResearchWorkflowConfig
```

Load optional ``research_workflow.yaml`` from *project_dir*.

### `ResearchStage`

*class — defined in `infrastructure.research.workflow`*

```python
class ResearchStage
```

A single stage in a research workflow.

### `ResearchWorkflow`

*class — defined in `infrastructure.research.workflow`*

```python
class ResearchWorkflow(stages: list[ResearchStage] | None=None)
```

Seven-stage research workflow plan.

### `ResearchWorkflowConfig`

*class — defined in `infrastructure.research.config`*

```python
class ResearchWorkflowConfig
```

Runtime configuration for the research workflow.

### `StageStatus`

*class — defined in `infrastructure.research.workflow`*

```python
class StageStatus(str, Enum)
```

Execution status of a research stage.

## Package: `infrastructure.rules`

### `build_rule_info`

*function — defined in `infrastructure.rules.rules_info`*

```python
build_rule_info(rule_dir: Path, program: str='') -> RuleInfo
```

Build a RuleInfo from a validated rule directory.

### `discover_rules`

*function — defined in `infrastructure.rules.discovery`*

```python
discover_rules(repo_root: Path | str) -> list[RuleInfo]
```

Discover all valid rules in the rules/ directory.

### `resolve_rule_root`

*function — defined in `infrastructure.rules.discovery`*

```python
resolve_rule_root(repo_root: Path | str, rule_name: str) -> Path
```

Resolve a rule directory by qualified name.

### `RuleInfo`

*class — defined in `infrastructure.rules.rules_info`*

```python
class RuleInfo
```

Information about a discovered rule.

### `validate_rule_structure`

*function — defined in `infrastructure.rules.validation`*

```python
validate_rule_structure(rule_dir: Path) -> tuple[bool, str]
```

Validate that a rule directory has the required structure.

## Package: `infrastructure.scientific`

### `benchmark_function`

*function — defined in `infrastructure.scientific.benchmarking`*

```python
benchmark_function(func: Callable[..., Any], test_inputs: list[Any], iterations: int=100) -> BenchmarkResult
```

Benchmark function performance across multiple inputs.

### `BenchmarkResult`

*class — defined in `infrastructure.scientific.benchmarking`*

```python
class BenchmarkResult
```

Container for benchmark results.

### `check_numerical_stability`

*function — defined in `infrastructure.scientific.stability`*

```python
check_numerical_stability(func: Callable[..., Any], test_inputs: list[Any], tolerance: float=1e-12) -> StabilityTest
```

Check numerical stability of a function across a range of inputs.

### `confirm_improvement`

*function — defined in `infrastructure.scientific.confirmation`*

```python
confirm_improvement(evaluate: Callable[[tuple[float, ...], int], float], candidate: tuple[float, ...], baseline_metric: float, seeds: Sequence[int], noise_scale: float, sigma: float=2.0) -> Confirmation
```

Confirm a candidate beats ``baseline_metric`` beyond the noise band.

### `Confirmation`

*class — defined in `infrastructure.scientific.confirmation`*

```python
class Confirmation
```

Outcome of a multi-seed confirmation check.

### `format_benchmark_report`

*function — defined in `infrastructure.scientific.benchmarking`*

```python
format_benchmark_report(benchmark_results: list[BenchmarkResult]) -> str
```

Format a Markdown performance analysis report from benchmark results.

### `StabilityTest`

*class — defined in `infrastructure.scientific.stability`*

```python
class StabilityTest
```

Container for numerical stability test results.

## Package: `infrastructure.search`

### `AbstractFetcher`

*symbol — defined in `infrastructure.search`*

### `ArxivBackend`

*symbol — defined in `infrastructure.search`*

### `BackendError`

*symbol — defined in `infrastructure.search`*

### `build_gemini_payload`

*symbol — defined in `infrastructure.search`*

### `build_gemini_tools`

*symbol — defined in `infrastructure.search`*

### `build_openai_payload`

*symbol — defined in `infrastructure.search`*

### `build_openai_tools`

*symbol — defined in `infrastructure.search`*

### `build_project_deep_research_request`

*symbol — defined in `infrastructure.search`*

### `collect_project_context`

*symbol — defined in `infrastructure.search`*

### `CrossrefBackend`

*symbol — defined in `infrastructure.search`*

### `DeepResearchAnalysis`

*symbol — defined in `infrastructure.search`*

### `DeepResearchCitation`

*symbol — defined in `infrastructure.search`*

### `DeepResearchClient`

*symbol — defined in `infrastructure.search`*

### `DeepResearchConfig`

*symbol — defined in `infrastructure.search`*

### `DeepResearchJobHandle`

*symbol — defined in `infrastructure.search`*

### `DeepResearchMCPServer`

*symbol — defined in `infrastructure.search`*

### `DeepResearchProjectContext`

*symbol — defined in `infrastructure.search`*

### `DeepResearchReportBundle`

*symbol — defined in `infrastructure.search`*

### `DeepResearchRequest`

*symbol — defined in `infrastructure.search`*

### `DeepResearchResult`

*symbol — defined in `infrastructure.search`*

### `DeepResearchSources`

*symbol — defined in `infrastructure.search`*

### `DEFAULT_GEMINI_AGENT`

*symbol — defined in `infrastructure.search`*

### `DEFAULT_OPENAI_MODEL`

*symbol — defined in `infrastructure.search`*

### `enrich_papers`

*symbol — defined in `infrastructure.search`*

### `ExaClient`

*symbol — defined in `infrastructure.search`*

### `ExaConfig`

*symbol — defined in `infrastructure.search`*

### `ExaError`

*symbol — defined in `infrastructure.search`*

### `FetchResult`

*symbol — defined in `infrastructure.search`*

### `FulltextFetcher`

*symbol — defined in `infrastructure.search`*

### `GeminiDeepResearchError`

*symbol — defined in `infrastructure.search`*

### `GeminiDeepResearchProvider`

*symbol — defined in `infrastructure.search`*

### `LiteratureClient`

*symbol — defined in `infrastructure.search`*

### `LocalBackend`

*symbol — defined in `infrastructure.search`*

### `merge_papers`

*symbol — defined in `infrastructure.search`*

### `MonidClient`

*symbol — defined in `infrastructure.search`*

### `MonidConfig`

*symbol — defined in `infrastructure.search`*

### `MonidError`

*symbol — defined in `infrastructure.search`*

### `OpenAIDeepResearchError`

*symbol — defined in `infrastructure.search`*

### `OpenAIDeepResearchProvider`

*symbol — defined in `infrastructure.search`*

### `Paper`

*symbol — defined in `infrastructure.search`*

### `PaperclipBackend`

*symbol — defined in `infrastructure.search`*

### `save_deep_research_result`

*symbol — defined in `infrastructure.search`*

### `save_deep_research_results`

*symbol — defined in `infrastructure.search`*

### `SearchBackend`

*symbol — defined in `infrastructure.search`*

### `SearchCache`

*symbol — defined in `infrastructure.search`*

### `SearchQuery`

*symbol — defined in `infrastructure.search`*

### `SearchResult`

*symbol — defined in `infrastructure.search`*

### `write_corpus`

*symbol — defined in `infrastructure.search`*

## Package: `infrastructure.sia`

### `AgentExecutionLog`

*symbol — defined in `infrastructure.sia`*

### `append_generation`

*symbol — defined in `infrastructure.sia`*

### `EvaluationResult`

*symbol — defined in `infrastructure.sia`*

### `GenerationArtifacts`

*symbol — defined in `infrastructure.sia`*

### `GenerationState`

*symbol — defined in `infrastructure.sia`*

### `init_context`

*symbol — defined in `infrastructure.sia`*

### `load_agent_execution`

*symbol — defined in `infrastructure.sia`*

### `read_results_json`

*symbol — defined in `infrastructure.sia`*

### `run_evaluation`

*symbol — defined in `infrastructure.sia`*

### `run_sia_loop`

*symbol — defined in `infrastructure.sia`*

### `RunConfig`

*symbol — defined in `infrastructure.sia`*

### `TaskLayout`

*symbol — defined in `infrastructure.sia`*

### `validate_task_dir`

*symbol — defined in `infrastructure.sia`*

### `write_results_json`

*symbol — defined in `infrastructure.sia`*

## Package: `infrastructure.skills`

### `build_manifest_payload`

*function — defined in `infrastructure.skills.discovery`*

```python
build_manifest_payload(skills: Sequence[SkillDescriptor]) -> dict[str, Any]
```

Build the canonical JSON-serializable manifest structure.

### `build_operations_payload`

*function — defined in `infrastructure.skills.operation_registry`*

```python
build_operations_payload(ops: Sequence[OperationDescriptor]) -> dict[str, Any]
```

Build the canonical JSON-serializable operations-manifest structure.

### `build_skill_index_markdown`

*function — defined in `infrastructure.skills.discovery`*

```python
build_skill_index_markdown(skills: Sequence[SkillDescriptor], *, search_roots: Sequence[str] | None=None) -> str
```

Build a human-readable Markdown index for discovered skills.

### `check_skill_contracts`

*function — defined in `infrastructure.skills.contracts`*

```python
check_skill_contracts(repo_root: Path | str) -> list[str]
```

Return all docs/prompts skill contract issues for a repository.

### `DEFAULT_OPERATION_SEARCH_ROOTS`

*constant — defined in `infrastructure.skills.operation_registry`*

```python
DEFAULT_OPERATION_SEARCH_ROOTS: tuple[str, ...] = ('infrastructure',)
```

### `DEFAULT_SKILL_SEARCH_ROOTS`

*constant — defined in `infrastructure.skills.discovery`*

```python
DEFAULT_SKILL_SEARCH_ROOTS: tuple[str, ...] = ('infrastructure', 'scripts', 'projects/templates', 'fonds/templates', 'rules...
```

### `discover_operations`

*function — defined in `infrastructure.skills.operation_registry`*

```python
discover_operations(repo_root: Path | str, *, search_roots: Sequence[str] | None=None) -> list[OperationDescriptor]
```

Discover every ``python -m``-invocable CLI under the search roots.

### `discover_skills`

*function — defined in `infrastructure.skills.discovery`*

```python
discover_skills(repo_root: Path | str, *, search_roots: Sequence[str] | None=None) -> list[SkillDescriptor]
```

Discover all ``SKILL.md`` files under configured roots and parse frontmatter.

### `iter_contract_skill_paths`

*function — defined in `infrastructure.skills.contracts`*

```python
iter_contract_skill_paths(repo_root: Path | str) -> Iterable[Path]
```

Yield workflow skill files whose metadata contract is enforced.

### `iter_skill_paths`

*function — defined in `infrastructure.skills.discovery`*

```python
iter_skill_paths(repo_root: Path, roots: Sequence[str]) -> Iterator[Path]
```

Yield absolute paths to ``SKILL.md`` under each root relative to ``repo_root``.

### `load_manifest`

*function — defined in `infrastructure.skills.discovery`*

```python
load_manifest(manifest_path: Path | str) -> dict[str, Any]
```

Load a manifest JSON file.

### `load_operations_manifest`

*function — defined in `infrastructure.skills.operation_registry`*

```python
load_operations_manifest(manifest_path: Path | str) -> dict[str, Any]
```

Load an operations manifest JSON file.

### `load_skill_descriptor`

*function — defined in `infrastructure.skills.discovery`*

```python
load_skill_descriptor(skill_path: Path, repo_root: Path) -> SkillDescriptor
```

Read a SKILL.md file and return a :class:`SkillDescriptor`.

### `manifest_matches_discovery`

*function — defined in `infrastructure.skills.discovery`*

```python
manifest_matches_discovery(repo_root: Path | str, manifest_path: Path | str, *, search_roots: Sequence[str] | None=None) -> tuple[bool, str]
```

Return whether the manifest matches current :func:`discover_skills` output.

### `manifest_skill_dicts_for_prompt`

*function — defined in `infrastructure.skills.discovery`*

```python
manifest_skill_dicts_for_prompt(skills: Sequence[SkillDescriptor]) -> list[dict[str, str]]
```

Compact rows suitable for logging or prompt injection.

### `operation_descriptors_as_json_serializable`

*function — defined in `infrastructure.skills.operation_registry`*

```python
operation_descriptors_as_json_serializable(ops: Sequence[OperationDescriptor]) -> list[dict[str, Any]]
```

Convert descriptors to plain JSON-serializable dicts.

### `OperationDescriptor`

*class — defined in `infrastructure.skills.operation_registry`*

```python
class OperationDescriptor
```

One agent-invocable CLI operation, discovered without importing it.

### `operations_manifest_matches_discovery`

*function — defined in `infrastructure.skills.operation_registry`*

```python
operations_manifest_matches_discovery(repo_root: Path | str, manifest_path: Path | str, *, search_roots: Sequence[str] | None=None) -> tuple[bool, str]
```

Return whether the manifest matches current :func:`discover_operations` output.

### `skill_descriptors_as_json_serializable`

*function — defined in `infrastructure.skills.discovery`*

```python
skill_descriptors_as_json_serializable(skills: Sequence[SkillDescriptor]) -> list[dict[str, Any]]
```

Convert descriptors to plain dicts (paths as strings) for JSON APIs.

### `SkillDescriptor`

*class — defined in `infrastructure.skills.discovery`*

```python
class SkillDescriptor
```

One discovered skill file with parsed YAML frontmatter.

### `split_yaml_frontmatter`

*function — defined in `infrastructure.skills.discovery`*

```python
split_yaml_frontmatter(source: str) -> tuple[dict[str, Any] | None, str]
```

Split leading YAML frontmatter from markdown body.

### `SubcommandInfo`

*class — defined in `infrastructure.skills.operation_registry`*

```python
class SubcommandInfo
```

One ``add_parser("name", help=...)`` subcommand discovered statically.

### `validate_skill_contract_file`

*function — defined in `infrastructure.skills.contracts`*

```python
validate_skill_contract_file(skill_path: Path | str) -> list[str]
```

Return contract issues for one workflow ``SKILL.md`` file.

### `write_operations_manifest`

*function — defined in `infrastructure.skills.operation_registry`*

```python
write_operations_manifest(repo_root: Path | str, output_path: Path | str | None=None, *, search_roots: Sequence[str] | None=None) -> Path
```

Write the operations manifest JSON for editors and agents.

### `write_skill_manifest`

*function — defined in `infrastructure.skills.discovery`*

```python
write_skill_manifest(repo_root: Path | str, output_path: Path | str | None=None, *, search_roots: Sequence[str] | None=None) -> Path
```

Write skill manifest JSON for editors and agents.

## Package: `infrastructure.steganography`

### `embed_steganography`

*function — defined in `infrastructure.steganography.core`*

```python
embed_steganography(input_pdf: Path, output_pdf: Path | None=None, config: SteganographyConfig | None=None, title: str='', authors: list[str] | None=None, keywords: list[str] | None=None, author_emails: list[str] | None=None) -> Path
```

Convenience function — create a processor and run it.

### `KmythAvailability`

*class — defined in `infrastructure.steganography.kmyth_adapter`*

```python
class KmythAvailability
```

Validation result for the optional Kmyth command-line tools.

### `KmythCommandError`

*class — defined in `infrastructure.steganography.kmyth_adapter`*

```python
class KmythCommandError(KmythError)
```

Raised when a Kmyth command exits unsuccessfully.

### `KmythError`

*class — defined in `infrastructure.steganography.kmyth_adapter`*

```python
class KmythError(RuntimeError)
```

Base class for Kmyth integration failures.

### `KmythSealOptions`

*class — defined in `infrastructure.steganography.kmyth_adapter`*

```python
class KmythSealOptions
```

Runtime options for invoking ``kmyth-seal``.

### `KmythUnavailableError`

*class — defined in `infrastructure.steganography.kmyth_adapter`*

```python
class KmythUnavailableError(KmythError)
```

Raised when Kmyth is requested but usable tools are unavailable.

### `resolve_build_timestamp`

*function — defined in `infrastructure.steganography.config`*

```python
resolve_build_timestamp(*, deterministic: bool | None=None, repo_root: Path | None=None) -> str
```

Return an ISO-8601 build timestamp.

### `seal_file_with_kmyth`

*function — defined in `infrastructure.steganography.kmyth_adapter`*

```python
seal_file_with_kmyth(input_path: Path, output_path: Path | None=None, *, options: KmythSealOptions | None=None) -> Path
```

Seal *input_path* with ``kmyth-seal`` and return the ``.ski`` path.

### `SteganographyConfig`

*class — defined in `infrastructure.steganography.config`*

```python
class SteganographyConfig
```

Configuration for steganographic PDF post-processing.

### `SteganographyProcessor`

*class — defined in `infrastructure.steganography.core`*

```python
class SteganographyProcessor(config: SteganographyConfig | None=None)
```

Orchestrates steganographic PDF post-processing.

### `validate_kmyth_installation`

*function — defined in `infrastructure.steganography.kmyth_adapter`*

```python
validate_kmyth_installation(*, binary_dir: str | Path | None=None, source_dir: str | Path | None=None) -> KmythAvailability
```

Validate that Kmyth source and command-line tools are available.

## Package: `infrastructure.tools`

### `build_tool_info`

*function — defined in `infrastructure.tools.tools_info`*

```python
build_tool_info(tool_dir: Path, program: str='') -> ToolInfo
```

Build a ToolInfo from a validated tool directory.

### `discover_tools`

*function — defined in `infrastructure.tools.discovery`*

```python
discover_tools(repo_root: Path | str) -> list[ToolInfo]
```

Discover all valid tools in the tools/ directory.

### `resolve_tool_root`

*function — defined in `infrastructure.tools.discovery`*

```python
resolve_tool_root(repo_root: Path | str, tool_name: str) -> Path
```

Resolve a tool directory by qualified name.

### `ToolInfo`

*class — defined in `infrastructure.tools.tools_info`*

```python
class ToolInfo
```

Information about a discovered tool.

### `validate_tool_structure`

*function — defined in `infrastructure.tools.validation`*

```python
validate_tool_structure(tool_dir: Path) -> tuple[bool, str]
```

Validate that a tool has the required structure.

## Package: `infrastructure.transmission`

### `transmission_barcode_strip`

*symbol — defined in `infrastructure.transmission`*

### `transmission_bookends`

*symbol — defined in `infrastructure.transmission`*

### `transmission_figure`

*symbol — defined in `infrastructure.transmission`*

### `transmission_models`

*symbol — defined in `infrastructure.transmission`*

### `transmission_page_check`

*symbol — defined in `infrastructure.transmission`*

## Package: `infrastructure.validation`

### `assign_severity`

*function — defined in `infrastructure.validation.repo.issue_categorizer`*

```python
assign_severity(issue: ValidationIssue) -> str
```

Assign severity level to an issue.

### `categorize_by_type`

*function — defined in `infrastructure.validation.repo.issue_categorizer`*

```python
categorize_by_type(issues: list[ValidationIssue]) -> dict[str, list[ValidationIssue]]
```

Categorize issues by their type and severity.

### `discover_markdown_files`

*function — defined in `infrastructure.validation.content.discovery`*

```python
discover_markdown_files(root: Path, *, scope: MarkdownDiscoveryScope='tree', repo_root: Path | None=None) -> list[Path]
```

Discover markdown files under *root* according to *scope*.

### `extract_text_from_pdf`

*function — defined in `infrastructure.validation.content.pdf_validator`*

```python
extract_text_from_pdf(pdf_path: Path) -> str
```

Extract all text content from a PDF file with robust error handling and fallbacks.

### `filter_false_positives`

*function — defined in `infrastructure.validation.repo.issue_categorizer`*

```python
filter_false_positives(issues: list[ValidationIssue]) -> list[ValidationIssue]
```

Filter out false positive issues from the list.

### `generate_audit_report`

*function — defined in `infrastructure.validation.repo.audit_orchestrator`*

```python
generate_audit_report(scan_results: ScanResults, output_format: str='markdown', show_green_flags: bool=False) -> str
```

Generate a formatted audit report with red/yellow/green severity flag classification.

### `generate_integrity_report`

*function — defined in `infrastructure.validation.integrity.checks`*

```python
generate_integrity_report(report: IntegrityReport) -> str
```

Generate a human-readable integrity report.

### `generate_issue_summary`

*function — defined in `infrastructure.validation.repo.issue_categorizer`*

```python
generate_issue_summary(issues: list[ValidationIssue]) -> dict[str, Any]
```

Generate a summary of issues by category and severity.

### `group_related_issues`

*function — defined in `infrastructure.validation.repo.issue_categorizer`*

```python
group_related_issues(issues: list[ValidationIssue]) -> list[list[ValidationIssue]]
```

Group related issues together for better analysis.

### `is_false_positive`

*function — defined in `infrastructure.validation.repo.issue_categorizer`*

```python
is_false_positive(issue: ValidationIssue) -> bool
```

Determine if an issue is likely a false positive.

### `LinkValidator`

*class — defined in `infrastructure.validation.integrity.link_validator`*

```python
class LinkValidator(repo_root: Path)
```

Validates markdown links and file references.

### `prioritize_issues`

*function — defined in `infrastructure.validation.repo.issue_categorizer`*

```python
prioritize_issues(issues: list[ValidationIssue]) -> list[ValidationIssue]
```

Sort issues by priority (severity, then type).

### `run_comprehensive_audit`

*function — defined in `infrastructure.validation.repo.audit_orchestrator`*

```python
run_comprehensive_audit(repo_root: Path, verbose: bool=False, include_code_validation: bool=True, include_directory_validation: bool=True, include_import_validation: bool=True, include_placeholder_validation: bool=True) -> ScanResults
```

Run audit across all validation modules and return categorized scan results.

### `scan_for_issues`

*function — defined in `infrastructure.validation.content.pdf_validator`*

```python
scan_for_issues(text: str) -> dict[str, int]
```

Scan extracted text for common rendering issues.

### `validate_citations`

*function — defined in `infrastructure.validation.content.validator_citations`*

```python
validate_citations(md_paths: list[str], repo_root: str | Path, bib_file: str | Path | list[str | Path] | None=None) -> list[DiagnosticEvent]
```

Verify every ``[@key]`` citation resolves in the project's BibTeX file(s).

### `validate_copied_outputs`

*function — defined in `infrastructure.validation.output.validator`*

```python
validate_copied_outputs(output_dir: Path, *, project_name: str | None=None, enabled_formats: Collection[str] | None=None, manuscript_dir: Path | None=None, inventory: StableOutputInventory | None=None, slides_profile: str='archive') -> bool
```

Validate all project outputs were copied successfully.

### `validate_figure_registry`

*function — defined in `infrastructure.validation.content.figure_validator`*

```python
validate_figure_registry(registry_path: Path, manuscript_dir: Path, *, require_accessibility: bool=False, additional_manuscript_dirs: Iterable[Path]=()) -> tuple[bool, list[str]]
```

Validate figure registry against manuscript references.

### `validate_images`

*function — defined in `infrastructure.validation.content.validator_images`*

```python
validate_images(md_paths: list[str], repo_root: str | Path, extra_search_dirs: list[str | Path] | None=None) -> list[DiagnosticEvent]
```

Validate that all referenced images exist in the filesystem.

### `validate_markdown`

*function — defined in `infrastructure.validation.content.markdown_validator`*

```python
validate_markdown(markdown_dir: str | Path, repo_root: str | Path, strict: bool=False) -> tuple[list[DiagnosticEvent], int]
```

Validate all markdown files in a directory.

### `validate_math`

*function — defined in `infrastructure.validation.content.validator_math`*

```python
validate_math(md_paths: list[str], repo_root: str | Path) -> list[DiagnosticEvent]
```

Validate mathematical equation formatting and labeling.

### `validate_output_structure`

*function — defined in `infrastructure.validation.output.validator`*

```python
validate_output_structure(output_dir: Path, *, require_pdf: bool=True, inventory: StableOutputInventory | None=None, enabled_formats: Collection[str] | None=None, inventory_mode: OutputInventoryMode=STABLE_OUTPUT_INVENTORY_MODE) -> OutputStructureResult
```

Validate complete output directory structure.

### `validate_pandoc_pitfalls`

*function — defined in `infrastructure.validation.content.validator_pitfalls`*

```python
validate_pandoc_pitfalls(md_paths: list[str], repo_root: str | Path) -> list[DiagnosticEvent]
```

Flag markdown patterns Pandoc converts to LaTeX ``\mid`` in text mode.

### `validate_pdf_rendering`

*function — defined in `infrastructure.validation.content.pdf_validator`*

```python
validate_pdf_rendering(pdf_path: Path, n_words: int=200) -> dict[str, Any]
```

Perform comprehensive validation of PDF rendering.

### `validate_refs`

*function — defined in `infrastructure.validation.content.validator_refs`*

```python
validate_refs(md_paths: list[str], repo_root: str | Path, labels: set[str], anchors: set[str]) -> list[DiagnosticEvent]
```

Validate cross-references, internal links, and external URLs.

### `verify_academic_standards`

*function — defined in `infrastructure.validation.integrity.checks`*

```python
verify_academic_standards(markdown_files: list[Path]) -> dict[str, bool]
```

Verify compliance with academic writing standards.

### `verify_cross_references`

*function — defined in `infrastructure.validation.integrity.checks`*

```python
verify_cross_references(markdown_files: list[Path]) -> dict[str, bool]
```

Verify cross-reference integrity in markdown files.

### `verify_data_consistency`

*function — defined in `infrastructure.validation.integrity.checks`*

```python
verify_data_consistency(data_files: list[Path]) -> dict[str, bool]
```

Verify data file consistency and integrity.

### `verify_file_integrity`

*function — defined in `infrastructure.validation.integrity.checks`*

```python
verify_file_integrity(file_paths: list[Path], expected_hashes: dict[str, str] | None=None) -> dict[str, bool]
```

Verify file integrity using hash comparison.

### `verify_output_integrity`

*function — defined in `infrastructure.validation.integrity.checks`*

```python
verify_output_integrity(output_dir: Path, manuscript_dir: Path | None=None) -> IntegrityReport
```

Perform comprehensive integrity verification of all outputs.
<!-- END:API_REFERENCE -->

---

## Summary

This API reference covers all public functions and classes exported
from `infrastructure/<pkg>/__init__.py` (`__all__`). For
project-specific code, see each project's `src/AGENTS.md`.

All infrastructure modules:

- Follow the thin-orchestrator pattern
- Maintain required test coverage (90% project, 60% infra)
- Include type hints
- Provide detailed docstrings

**Related Documentation:**

- [Modules Guide](../modules/modules-guide.md) — Usage examples
- [Infrastructure Docs](../../infrastructure/AGENTS.md) — Infrastructure module implementation
- [Project Source Docs](../../projects/templates/template_code_project/src/AGENTS.md) — Project module implementation
- [Best Practices](../best-practices/best-practices.md) — Usage recommendations