version: "1.0.0" name: dossier-builder description: Generate complete buyer research reports and dealer proposals as HTML and PDF. Use for vehicle comparisons, market research, shortlists and default report delivery during a car-buying workflow. Triggers include "build dossier", "generate market research PDF", "dealer dossier", "decision document", "make dossier for dealer", "生成 dossier", "制作 PDF", "完整购车报告", "generar el dossier para el concesionario", and "crear el PDF de investigacion de mercado".

Decision Dossier Builder

Deliver the buying report from the evidence already collected. A broad buying workflow includes this artifact without a separate request for detail or a PDF. The agent prepares the config; do not ask the buyer to populate schema fields.

Choose the document purpose first

The first is the default during market research. The second is a later outward document. Do not make the proposal's two-quote or complete-fee requirement block useful research. Both have separate demo/live privacy modes; research versus proposal is not the same choice as synthetic versus real data.

Generate the buyer research packet

Follow report delivery. Reuse the current private cycle, criteria and captured evidence. Produce substantive comparisons, configuration tradeoffs, delivered-cost uncertainties, suitability, ownership risks, shortlist rationale and next actions, rather than a long intake questionnaire or validation log. Use the research schema to assemble structured input.

python skills/orchestrator/scripts/generate_research_report.py --mode live --config cycles/session/research_config.json --output cycles/session/buyer_research.html --to-pdf cycles/session/buyer_research.pdf

Live relative paths resolve under verified private DATA. Keep master_comparison.md alongside the report. When a scenario has fictional buyer criteria but real source observations, use live private storage and label every fictional criterion as an assumption; never turn observed inventory into public demo fixtures. List asking prices as asking prices, leave missing fees unknown, and explain what evidence would change the shortlist.

Inspect every generated PDF page and the substance checklist before delivering the HTML/PDF links. Do not request extra permission to render local artifacts already implied by the buying task. Source/PDF problems must be visible; preserve useful partial work and resolve the remaining dependency where possible.

The remainder of this document describes the stricter dealer proposal. Its generator checks arithmetic, required fields, source dates and evidence integrity. Those checks cannot determine whether a source supports a claim or whether a dealer still honors its terms. Read the sources before making claims.

Choose the mode

• demo accepts only the generated synthetic EN/CN/ES fixtures. Every page is

labeled as a synthetic demonstration that must not be presented as real. Changing a fixture to include personal information is rejected.

• live requires a current config, evidence files, and output files under the

proven private companion DATA directory. Missing initialization, public or unknown repository visibility, and paths outside that directory fail.

Do not turn the demo into a real proposal by changing only its mode. Replace fictional input with researched facts and buyer-approved statements, and bind those fields to the actual source artifacts. Do not claim a confirmed quote, clean history, active warranty, certification, payment method, or closing commitment without the matching evidence. Keep the buyer's private walk-away ceiling out of this dealer-facing document.

Build a synthetic demonstration

From the repository root, choose an output directory outside the public tool repository. For example, replace <temporary-directory> below with a system temporary directory:

python skills/orchestrator/scripts/generate_dossier.py --mode demo --config skills/orchestrator/assets/dossier_config_template.yaml --output <temporary-directory>/dossier.html --to-pdf <temporary-directory>/dossier.pdf

For Chinese or Spanish, select dossier_config_template_cn.yaml or dossier_config_template_es.yaml. LANGUAGE chooses the corresponding shipped HTML template. --template may explicitly select a shipped EN/CN/ES template. The localized templates translate fixed labels; arbitrary input prose is not translated. The public fixtures are formatting demonstrations and contain some English sample content.

Fixtures are regenerated by python tools/make_fixtures.py; do not edit their output files manually. Python needs PyYAML for YAML input and pypdf to verify PDF output. Use Chromium 131 or newer for printed page-margin notices. An available wkhtmltopdf fallback is attempted when Chromium is absent, but output still fails verification if that renderer cannot print the required notice on every page.

Build a real proposal

1. Resolve the private DATA directory with tools/runtime_paths.py. Create and

store the config and source artifacts there. Never use a path in the public repository for real buyer information or source observations.

1. Read each source. Record its date, provenance, hash, and the fields it supports.

Require written OTD quotes for the same registration jurisdiction, with their conditions and expiration dates. A listing price is not a written OTD quote.

1. Fill every placeholder field used by the chosen template, including buyer

payment, financing, trade-in, and plate plans. Use DOSSIER_MODE: live, SYNTHETIC: false, and today's quoted DATE.

1. Run the generator. Relative live paths resolve under private DATA, so the

following paths are not relative to the public working tree:

python skills/orchestrator/scripts/generate_dossier.py --mode live --config dossiers/session/config.yaml --output dossiers/session/proposal.html --to-pdf dossiers/session/proposal.pdf

1. Open the PDF and inspect every page for legibility, clipping, broken tables,

and untranslated text. Recheck amounts and source references. Report the actual page count; length changes with the supplied content.

The shell entrypoint html_to_pdf.sh takes the same generator arguments. It regenerates the validated dossier instead of accepting arbitrary input HTML. --allow-missing was removed: missing or unresolved content must be completed before a dossier is emitted.

Monetary contract

Use decimal strings such as "27500.00". Dollar signs, scientific notation, negative charges, malformed separators, nonfinite numbers, and fractions of a cent are rejected. The generator checks:

TARGET_OTD = PROPOSED_SALES + TAX_AMOUNT + REG_AMOUNT + TITLE_AMOUNT
             + DOC_AMOUNT + OTHER_FEES - TRADE_IN_CREDIT - REBATE_AMOUNT
TAX_AMOUNT = round_half_up(TAX_BASE * TAX_RATE / 100, 2) + TAX_ADJUSTMENT

Supply every field, including explicit zero values. TAX_RATE is a percentage: "8" means 8%. TAX_ADJUSTMENT is signed and must be supported when used for a fixed adjustment. Derive the taxable base, credits, title, and registration charges from current applicable rules; this arithmetic check does not decide which jurisdictional tax mechanism or exemptions apply. Consult the otd-calculator and state-fee-lookup helpers first. The tax basis and adjustment row in the PDF is informational and is not added to the total a second time.

Quote and evidence contract

QUOTES contains at least two distinct complete offers. Every record requires:

All quote records are rendered. Do not provide legacy COMP_* fields or a manually asserted count of confirmed offers; those display values are derived.

Each EVIDENCE record requires id, kind, source, source_date, and supports. Dates use quoted YYYY-MM-DD strings. Live evidence additionally requires artifact (a private DATA path) and sha256 (the actual file hash). Supported live kinds are dealer_quote, listing, official, and buyer_statement. Use an HTTPS provenance URL, or a descriptive provenance label for a buyer statement; the artifact preserves the inspected content.

supports lists exact scalar field names and quote:<id> references. Each nonempty live scalar fact or buyer statement needs coverage, except proposal metadata and the buyer's proposed sales price and target. Each written quote must reference dealer_quote evidence supporting that quote ID. Offer/listing sources must be no older than 14 days; official documents and buyer statements must have been reviewed within 90 days. Future dates are rejected. Keep original source publication dates inside the artifact when source_date records a fresh review of an older policy.

Record sources for warranty, certification, regional statistics, and narrative claims as carefully as for quotes. Presence and matching SHA-256 establish that the stored artifact has not changed; they do not prove its truth or the accuracy of the operator's interpretation. The PDF displays source IDs, dates, and provenance without printing local artifact paths.

PDF and output checks

• Chromium runs with a fresh temporary profile and --no-pdf-header-footer.
• The default rendering timeout is 60 seconds; --pdf-timeout accepts values

above zero through 300 seconds.

• A new staging PDF must parse, contain pages, repeat the exact mode notice on

every page, and have no printed file:/// URL before it replaces the requested output. A renderer failure or timeout cannot be mistaken for success because an old PDF exists.

• Inserted config text is HTML-escaped. Deliberate markup belongs in the shipped

templates; arbitrary templates and raw config HTML are not accepted.

Return the mode, private config path, HTML/PDF paths, actual page count, monetary validation result, evidence completeness result, and scope of visual inspection. For a demo, explicitly say that no real quote or negotiation was performed. For live work, distinguish source review from the generator's mechanical checks.

Related helpers

• ../orchestrator/scripts/generate_dossier.py: validation and rendering
• ../orchestrator/assets/dossier_template*.html: EN/CN/ES layout
• ../quote-evidence-collector/SKILL.md: source collection
• ../otd-calculator/SKILL.md: supported OTD calculations
• ../state-fee-lookup/SKILL.md: jurisdictional tax and fee verification

When installed through directory links, resolve this SKILL.md to its source directory before following relative file paths. Those paths refer to the repository layout.