% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/api-export-bundles.R
\name{export_summary_appendix}
\alias{export_summary_appendix}
\title{Export manuscript appendix tables from validated summary surfaces}
\usage{
export_summary_appendix(
  x,
  output_dir = ".",
  prefix = "mfrmr_appendix",
  include_html = TRUE,
  preset = c("all", "recommended", "compact", "methods", "results", "diagnostics",
    "reporting"),
  overwrite = FALSE,
  zip_bundle = FALSE,
  zip_name = NULL,
  digits = 3,
  top_n = 10,
  preview_chars = 160
)
}
\arguments{
\item{x}{A supported \code{summary()} source, a prebuilt
\code{\link[=build_summary_table_bundle]{build_summary_table_bundle()}} result, or a named list of such objects.}

\item{output_dir}{Directory where files will be written.}

\item{prefix}{File-name prefix for written artifacts.}

\item{include_html}{If \code{TRUE}, also write a lightweight HTML appendix page.}

\item{preset}{Appendix table-selection preset:
\code{"all"} keeps every returned summary table,
\code{"recommended"} keeps manuscript-facing summary tables while dropping
bridge-only or preview-only surfaces, and
\code{"compact"} keeps a smaller reviewer-facing subset.
Section-aware presets \code{"methods"}, \code{"results"}, \code{"diagnostics"}, and
\code{"reporting"} keep only the returned tables classified to those appendix
sections in the summary-table catalog.}

\item{overwrite}{If \code{FALSE}, refuse to overwrite existing files.}

\item{zip_bundle}{If \code{TRUE}, attempt to zip the written appendix artifacts.}

\item{zip_name}{Optional zip-file name. Defaults to \code{"{prefix}_appendix.zip"}.}

\item{digits}{Digits forwarded when raw objects must be normalized through
\code{\link[=build_summary_table_bundle]{build_summary_table_bundle()}}.}

\item{top_n}{Row cap forwarded when raw objects must be normalized through
\code{\link[=build_summary_table_bundle]{build_summary_table_bundle()}}.}

\item{preview_chars}{Character cap forwarded when APA-output summaries must
be normalized through \code{\link[=build_summary_table_bundle]{build_summary_table_bundle()}}.}
}
\value{
A named list of class \code{mfrm_summary_appendix_export} with:
\itemize{
\item \code{summary}
\item \code{written_files}
\item \code{selection_summary}
\item \code{selection_table_summary}
\item \code{selection_section_table_summary}
\item \code{selection_handoff_table_summary}
\item \code{selection_handoff_preset_summary}
\item \code{selection_handoff_summary}
\item \code{selection_handoff_bundle_summary}
\item \code{selection_handoff_role_summary}
\item \code{selection_handoff_role_section_summary}
\item \code{selection_role_summary}
\item \code{selection_section_summary}
\item \code{selection_catalog}
\item \code{settings}
\item \code{notes}
}
}
\description{
Export manuscript appendix tables from validated summary surfaces
}
\details{
This helper is the narrow public bridge from validated \code{summary()} surfaces
to manuscript appendix artifacts. It accepts the same reporting objects that
\code{\link[=build_summary_table_bundle]{build_summary_table_bundle()}} supports, exports their table bundles as CSV,
and optionally assembles a lightweight HTML appendix page.

Fit-level caveats are exported through the \code{analysis_caveats} role, and
pre-fit score-support caveats are exported through the
\code{score_category_caveats} role. Both roles are classified as diagnostics, so
they remain available under \code{"recommended"} and \code{"diagnostics"} presets when
the source summary contains caveat rows.

Precision-review summaries keep \code{fit_separation_basis} in the exported
precision-review role so fit, ZSTD, separation/reliability/strata, and
package QC thresholds can be reported without turning them into release or
recovery success gates.
Fit-measure and FACETS fit-review summaries keep df/ZSTD sensitivity and
optional external FACETS matching tables in the same precision-review lane.

Parameter-recovery studies can be exported by passing
\code{\link[=evaluate_mfrm_recovery]{evaluate_mfrm_recovery()}} or \code{\link[=assess_mfrm_recovery]{assess_mfrm_recovery()}} output directly. The
exported bundle keeps the ADEMP-style simulation basis, recovery metrics,
replication status, adequacy checklist, thresholds, and next actions in
separate appendix-ready tables.

Recovery-validation summaries from the packaged validation protocol can be
exported by passing \code{summary(validation)}, including top-line release
decisions, condition notes, diagnostic notes, and domain decisions.

Unlike \code{\link[=export_mfrm_bundle]{export_mfrm_bundle()}}, this helper does not require a fitted model.
It is intended for the stage where compact reporting summaries already exist
and the task is to hand off appendix-ready tables, catalogs, and reporting
maps.
}
\section{Typical workflow}{

\enumerate{
\item Build \code{summary(...)} objects from fit, diagnostics, data description,
reporting checklist, or APA outputs.
\item Call \code{export_summary_appendix(...)} on one object or a named list.
\item Hand off the written CSV/HTML appendix artifacts to manuscript or QA
workflows.
}
}

\examples{
\donttest{
toy <- load_mfrmr_data("example_core")
fit <- fit_mfrm(toy, "Person", c("Rater", "Criterion"), "Score",
                method = "JML", maxit = 30)
diag <- diagnose_mfrm(fit, residual_pca = "none")
appendix <- export_summary_appendix(
  list(fit = fit, diagnostics = diag),
  output_dir = tempdir(),
  prefix = "mfrmr_appendix_example",
  include_html = TRUE,
  overwrite = TRUE
)
appendix$summary
}
}
\seealso{
\code{\link[=build_summary_table_bundle]{build_summary_table_bundle()}}, \code{\link[=export_mfrm_bundle]{export_mfrm_bundle()}},
\code{\link[=apa_table]{apa_table()}}
}
