Skip to content

siril9/presentation-skill / plugins/presentation-skill/skills/presentation-skill

presentation-skill

Flagged

Build, edit, redesign, render, and verify content-led, structurally diverse, clean, editable, reproducible PowerPoint `.pptx` decks. Use for scientific, lab, clinical, consulting, board, investor, editorial, policy, and operational presentations where alignment, readability, contrast, and balanced density matter.

FileKindSize
DESIGN.mdmarkdown13.7 KB
DISCOVERY.mdmarkdown6.6 KB
LICENSEother1.0 KB
SKILL.mdskill md14.7 KB
agents/discovery.jsonconfig8.2 KB
agents/openai.yamlconfig309 B
examples/outline.jsonconfig3.4 KB
package-lock.jsonmanifest22.0 KB
package.jsonmanifest1.8 KB
references/agent_picker.mdmarkdown1.9 KB
references/alignment_and_coherence.mdmarkdown2.1 KB
references/assets/visual_references/editorial_chart.jpgbinary53.2 KB
references/assets/visual_references/editorial_decision.jpgbinary100.4 KB
references/assets/visual_references/editorial_focal_metric.jpgbinary45.4 KB
references/assets/visual_references/editorial_pilot.jpgbinary62.0 KB
references/assets/visual_references/lab-native-method.jpgbinary53.9 KB
references/assets/visual_references/lab-residual-panels.jpgbinary64.8 KB
references/assets/visual_references/lab_cover.jpgbinary39.8 KB
references/assets/visual_references/lab_endpoints.jpgbinary70.8 KB
references/assets/visual_references/lab_evidence_gate.jpgbinary67.3 KB
references/assets/visual_references/lab_trend.jpgbinary60.5 KB
references/assets/visual_references/operations_handoffs.jpgbinary87.2 KB
references/assets/visual_references/operations_owner_register.jpgbinary87.2 KB
references/assets/visual_references/operations_queue.jpgbinary81.8 KB
references/assets/visual_references/operations_tradeoff.jpgbinary99.9 KB
references/benchmark_protocol.mdmarkdown12.1 KB
references/codex_guardrails.mdmarkdown10.3 KB
references/composition_grammar_catalog.mdmarkdown4.0 KB
references/deck_creation.mdmarkdown1.4 KB
references/deck_workspace_mode.mdmarkdown34.4 KB
references/design_philosophy.mdmarkdown5.5 KB
references/dynamic_design_and_subagents.mdmarkdown12.3 KB
references/editing.mdmarkdown12.4 KB
references/external_best_practices.mdmarkdown1.7 KB
references/large_style_corpus_sources.jsonconfig22.7 KB
references/model_adaptive_workflow.mdmarkdown6.6 KB
references/outline_schema.mdmarkdown44.8 KB
references/planning_schema.mdmarkdown54.8 KB
references/pptxgenjs.mdmarkdown7.6 KB
references/preview_extension.mdmarkdown1.7 KB
references/reference_script_patterns.mdmarkdown13.5 KB
references/renderer_role_contracts_v2.jsonconfig38.2 KB
references/reproducible_workflow.mdmarkdown5.1 KB
references/speed_and_rendering.mdmarkdown4.6 KB
references/style_grammar_index.jsonconfig364.2 KB
references/style_inspiration_corpus.jsonconfig32.9 KB
references/style_reference_catalog.mdmarkdown23.9 KB
references/style_reference_sources.jsonconfig35.8 KB
references/style_token_atlas.jsonconfig174.7 KB
references/subagent_patterns.mdmarkdown10.2 KB
references/visual_qa_prompt.mdmarkdown4.9 KB
references/visual_reference_catalog.jsonconfig26.6 KB
references/visual_reference_catalog.mdmarkdown6.0 KB
schemas/deck_ir.schema.jsonconfig9.5 KB
schemas/renderer_capabilities_v2.jsonconfig701 B
scripts/accessibility_qa.pyscript24.8 KB
scripts/action_registry.pyscript12.5 KB
scripts/add_slide.pyscript8.6 KB
scripts/advance_delivery.pyscript88.2 KB
scripts/advance_workspace.pyscript150.3 KB
scripts/apply_artifact_manifest_bindings.pyscript54.1 KB
scripts/apply_atom_composition.pyscript8.2 KB
scripts/apply_data_analysis_handoff.pyscript67.0 KB
scripts/apply_deck_intake_answers.pyscript35.6 KB
scripts/apply_design_contract.pyscript71.7 KB
scripts/apply_outline_authoring_handoff.pyscript23.7 KB
scripts/apply_pptx_style_fragment.pyscript19.7 KB
scripts/asset_stage.pyscript24.6 KB
scripts/audition_styles.pyscript8.7 KB
scripts/benchmark_decks.pyexecutablescript45.4 KB
scripts/build_deck.pyexecutablescript173.6 KB
scripts/build_deck_pptxgenjs.jsexecutablescript72.7 KB
scripts/build_large_style_corpus_contact_sheets.pyscript18.1 KB
scripts/build_workspace.pyscript126.2 KB
scripts/clean_unpacked.pyscript12.9 KB
scripts/compact_source_footers.pyscript17.8 KB
scripts/composition_grammar_catalog.pyscript30.3 KB
scripts/deck_benchmark.pyscript71.1 KB
scripts/deck_intake.pyscript6.9 KB
scripts/deck_ir.pyscript47.5 KB
scripts/design_catalog_selector.pyscript17.4 KB
scripts/design_rules_qa.pyscript24.8 KB
scripts/design_tokens.pyscript20.3 KB
scripts/edit_deck.pyscript8.4 KB
scripts/emit_content_research.pyscript4.6 KB
scripts/emit_data_analysis_prompt.pyscript30.1 KB
scripts/emit_deck_intake_prompt.pyexecutablescript19.9 KB
scripts/emit_deck_start_packet.pyscript97.1 KB
scripts/emit_design_contract_prompt.pyscript66.2 KB
scripts/emit_outline_authoring_prompt.pyscript35.4 KB
scripts/emit_outline_critique.pyscript11.6 KB
scripts/emit_style_content_router.pyscript49.6 KB
scripts/extract_outline.pyexecutablescript4.1 KB
scripts/extract_pptx_style.pyscript33.2 KB
scripts/fetch_wikimedia_cc.pyscript8.6 KB
scripts/finalize_quick_deck.pyscript17.6 KB
scripts/generate_openai_image.pyscript5.6 KB
scripts/init_deck_workspace.pyscript74.4 KB
scripts/inspect_artifact_manifest.pyscript29.8 KB
scripts/inventory.pyscript10.6 KB
scripts/iterate_deck.pyexecutablescript10.2 KB
scripts/layout_lint.pyscript40.4 KB
scripts/log_skill_telemetry.pyscript6.9 KB
scripts/model_adaptive_workflow.pyscript28.0 KB
scripts/office_package_hash.pyscript1.6 KB
scripts/pack_pptx.pyscript5.7 KB
scripts/palette_from_topic.pyscript4.1 KB
scripts/plan_research_assets.pyscript13.1 KB
scripts/preflight.pyscript136.9 KB
scripts/present.pyscript9.6 KB
scripts/python_runtime.pyscript787 B
scripts/qa_gate.pyexecutablescript27.4 KB
scripts/qa_visual_gate.pyexecutablescript8.5 KB
scripts/reference_deck.pyscript12.7 KB
scripts/render_cache.pyscript3.9 KB
scripts/render_mermaid.pyscript8.9 KB
scripts/render_slides.pyexecutablescript19.4 KB
scripts/repair_packet.pyscript14.7 KB
scripts/report_delivery_readiness.pyscript107.6 KB
scripts/report_workspace_readiness.pyscript244.6 KB
scripts/requirements-runtime.txtmarkdown472 B
scripts/role_layout_contracts.pyscript10.6 KB
scripts/runtime_doctor.pyscript6.3 KB
scripts/scaffold_figure_artifacts.pyscript92.3 KB
scripts/source_fidelity.pyscript30.5 KB
scripts/structural_diversity_v2.pyscript32.5 KB
scripts/style_atom_router.pyscript14.5 KB
scripts/style_inspiration_corpus.pyscript15.1 KB
scripts/style_reference_catalog.pyscript142.8 KB
scripts/style_reference_sources.pyscript12.7 KB
scripts/style_treatment_profiles.pyscript26.0 KB
scripts/summarize_skill_log.pyscript7.0 KB
scripts/taste_grammar_catalog.pyscript27.0 KB
scripts/test_structural_diversity_v2.pyscript4.9 KB
scripts/text_fit.pyscript23.6 KB
scripts/thumbnail.pyscript9.2 KB
scripts/trim_image_whitespace.pyexecutablescript5.4 KB
scripts/unpack_pptx.pyscript8.3 KB
scripts/upgrade_renderer_role_contracts_v2.pyscript7.3 KB
scripts/validate_planning.pyscript169.2 KB
scripts/verify_narration.pyscript10.6 KB
scripts/visual_qa.pyscript7.7 KB
scripts/visual_review.pyscript41.1 KB
scripts/visual_review_receipt.pyscript8.3 KB
scripts/workflow_atom_context.pyscript17.3 KB
templates/pptxgenjs/README.mdmarkdown8.4 KB
templates/pptxgenjs/presets.jsscript5.6 KB
templates/pptxgenjs/readable_role_layouts.jsscript17.5 KB
templates/pptxgenjs/render_plan.jsscript12.6 KB
templates/pptxgenjs/role_layout_contracts.jsscript4.7 KB
templates/pptxgenjs/slides.jsscript451.0 KB
templates/pptxgenjs/space_allocation.jsscript1.6 KB

scripts/composition_grammar_catalog.py

View on GitHub
#!/usr/bin/env python3
"""Build and route the canonical eight deck composition grammars."""

from __future__ import annotations

import argparse
import copy
import hashlib
import json
import re
from collections import Counter
from pathlib import Path
from typing import Any

from deck_intake import build_deck_intake, intake_authoring_prompt, normalize_intake_answers
from model_adaptive_workflow import (
    PROFILE_ALIASES,
    PROFILE_HELP,
    VISUAL_REFERENCE_POLICY,
    compact_authoring_diagnostics,
    minimal_payload_examples,
    resolve_profile,
    select_visual_reference_hints,
)
from style_treatment_profiles import preset_treatment_profile
from taste_grammar_catalog import (
    COMPOSITION_GRAMMARS,
    PRESET_TO_GRAMMAR,
    ROLE_NAMES,
    build_taste_grammar_catalog,
    renderer_role_systems_for_grammar,
    validate_taste_grammar_catalog,
)
from role_layout_contracts import renderer_role_contracts_for_grammar


CATALOG_VERSION = "composition_grammar_catalog_v1"

REQUESTED_VARIANT_HINTS = {
    "chart": ("chart", "plot", "graph", "trend"),
    "table": ("table", "ledger", "rows", "matrix data"),
    "scientific-figure": ("scientific figure", "multi-panel", "figure panels"),
    "image-sidebar": ("image sidebar", "figure sidebar", "map", "microscopy"),
    "lab-run-results": ("lab results", "run results", "assay results", "qc table"),
    "comparison-2col": ("comparison", "before and after", "versus", "tradeoff"),
    "matrix": ("matrix", "quadrant", "2x2"),
    "timeline": ("timeline", "roadmap", "milestones"),
    "flow": ("flow", "process", "workflow", "architecture"),
    "stats": ("stats", "metrics", "kpis", "dashboard"),
    "kpi-hero": ("hero metric", "big number", "single kpi"),
}

STOPWORDS = {
    "a", "an", "and", "are", "as", "at", "be", "by", "can", "deck", "for", "from",
    "in", "into", "is", "it", "of", "on", "or", "presentation", "slide", "slides", "the",
    "this", "to", "use", "with",
}


def _as_dict(value: Any) -> dict[str, Any]:
    return value if isinstance(value, dict) else {}


def _as_list(value: Any) -> list[Any]:
    return value if isinstance(value, list) else []


def _ordered_unique(values: list[Any]) -> list[str]:
    out: list[str] = []
    for value in values:
        text = str(value or "").strip()
        if text and text not in out:
            out.append(text)
    return out


def _tokens(value: str) -> set[str]:
    return {
        token
        for token in re.findall(r"[a-z0-9]+", str(value or "").lower())
        if len(token) > 1 and token not in STOPWORDS
    }


def _requested_variants(text: str) -> list[str]:
    lower = str(text or "").lower()
    return [
        variant
        for variant, hints in REQUESTED_VARIANT_HINTS.items()
        if any(hint in lower for hint in hints)
    ]


def _structural_signature(grammar: dict[str, Any]) -> str:
    payload = {
        "grammar_id": grammar.get("grammar_id"),
        "role_system_ids": {
            role: grammar.get(f"{role}_system_id")
            for role in ROLE_NAMES
        },
        "narrative_arc": grammar.get("narrative_arc"),
        "density": grammar.get("density"),
        "grid": grammar.get("grid"),
        "reading_path": grammar.get("reading_path"),
        "invariant_moves": grammar.get("invariant_moves"),
        "forbidden_moves": grammar.get("forbidden_moves"),
    }
    encoded = json.dumps(payload, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
    return hashlib.sha256(encoded.encode("utf-8")).hexdigest()


def _record_from_grammar(grammar_id: str, *, style_preset: str = "") -> dict[str, Any]:
    spec = copy.deepcopy(COMPOSITION_GRAMMARS[grammar_id])
    presets = [str(value) for value in spec.get("style_presets") or []]
    resolved_preset = style_preset if style_preset in presets else presets[0]
    role_systems = renderer_role_systems_for_grammar(grammar_id, preset=resolved_preset)
    role_contracts = renderer_role_contracts_for_grammar(grammar_id, preset=resolved_preset)
    preferred_role_variants = _as_dict(spec.get("preferred_role_variants"))
    role_variant_map = {
        role: str((_as_list(preferred_role_variants.get(role)) or ["standard"])[0])
        for role in ROLE_NAMES
    }
    rhythm_treatments = list(ROLE_NAMES)
    rhythm_pattern = [role_variant_map[role] for role in rhythm_treatments]
    profile = preset_treatment_profile(resolved_preset)
    record: dict[str, Any] = {
        "grammar_id": grammar_id,
        "catalog_version": CATALOG_VERSION,
        "style_preset": resolved_preset,
        "style_presets": presets,
        "family": profile.get("family"),
        "lane": spec.get("lane"),
        "description": spec.get("description"),
        "best_for": _ordered_unique([*presets, *map(str, spec.get("prompt_keywords") or [])]),
        "prompt_keywords": list(spec.get("prompt_keywords") or []),
        "rhythm_treatments": rhythm_treatments,
        "rhythm_pattern": rhythm_pattern,
        "role_variant_map": role_variant_map,
        "preferred_variants": _ordered_unique(
            [variant for role in ROLE_NAMES for variant in _as_list(preferred_role_variants.get(role))]
        ),
        "renderer_bias": copy.deepcopy(profile.get("renderer_treatment_defaults") or {}),
        "renderer_role_systems_v1": role_systems,
        "renderer_role_contracts_v2": role_contracts,
        "narrative_arc": copy.deepcopy(spec.get("narrative_arc") or {}),
        "density": copy.deepcopy(spec.get("density") or {}),
        "grid": copy.deepcopy(spec.get("grid") or {}),
        "reading_path": list(spec.get("reading_path") or []),
        "preferred_role_variants": preferred_role_variants,
        "invariant_moves": list(spec.get("invariant_moves") or []),
        "forbidden_moves": list(spec.get("forbidden_moves") or []),
        "distinctive_moves": list(spec.get("invariant_moves") or []),
        "avoid": list(spec.get("forbidden_moves") or []),
        "mix_rule": (
            "Keep one composition grammar coherent across the deck. Borrow isolated treatment ideas, "
            "but do not merge complete role systems or page systems."
        ),
        "max_consecutive_same_variant": 2,
    }
    for role in ROLE_NAMES:
        record[f"{role}_system_id"] = role_systems[f"{role}_system_id"]
    record["structural_signature"] = _structural_signature(record)
    return record


def build_composition_grammar_catalog() -> dict[str, Any]:
    records = [_record_from_grammar(grammar_id) for grammar_id in COMPOSITION_GRAMMARS]
    taste_catalog = build_taste_grammar_catalog()
    return {
        "catalog_version": CATALOG_VERSION,
        "taste_catalog_version": taste_catalog.get("catalog_version"),
        "renderer_role_systems_version": taste_catalog.get("renderer_role_systems_version"),
        "grammar_count": len(records),
        "preset_count": len(PRESET_TO_GRAMMAR),
        "preset_to_grammar": dict(PRESET_TO_GRAMMAR),
        "role_system_counts": {
            role: len(_as_list(_as_dict(taste_catalog.get("role_system_catalogs")).get(f"{role}_systems")))
            for role in ROLE_NAMES
        },
        "narrative_arc_count": len(
            {
                str(_as_dict(record.get("narrative_arc")).get("arc_id") or "")
                for record in records
            }
        ),
        "records": records,
    }


def validate_composition_grammar_catalog(catalog: dict[str, Any] | None = None) -> dict[str, Any]:
    payload = catalog or build_composition_grammar_catalog()
    records = _as_list(payload.get("records"))
    failures: list[str] = []
    ids: list[str] = []
    signatures: list[str] = []
    preset_map = _as_dict(payload.get("preset_to_grammar"))
    usage = Counter(map(str, preset_map.values()))
    for record in records:
        if not isinstance(record, dict):
            failures.append("non-object grammar record")
            continue
        grammar_id = str(record.get("grammar_id") or "")
        ids.append(grammar_id)
        signatures.append(str(record.get("structural_signature") or ""))
        for role in ROLE_NAMES:
            if not str(record.get(f"{role}_system_id") or "").strip():
                failures.append(f"{grammar_id}: missing {role}_system_id")
        for key in (
            "narrative_arc", "density", "grid", "reading_path", "preferred_role_variants",
            "invariant_moves", "forbidden_moves", "renderer_role_systems_v1", "renderer_role_contracts_v2",
        ):
            if record.get(key) in (None, {}, []):
                failures.append(f"{grammar_id}: missing {key}")
    if len(records) != 8:
        failures.append(f"grammar_count={len(records)} expected=8")
    if set(ids) != set(COMPOSITION_GRAMMARS):
        failures.append("composition grammar IDs do not match the canonical eight")
    if len(set(ids)) != len(ids):
        failures.append("duplicate grammar ids")
    if len(set(signatures)) != len(signatures):
        failures.append("duplicate structural signatures")
    if len(preset_map) != 13:
        failures.append(f"preset_count={len(preset_map)} expected=13")
    if max(usage.values(), default=0) > 2:
        failures.append("a composition grammar is mapped to more than two presets")
    taste_summary = validate_taste_grammar_catalog()
    if not taste_summary.get("passed"):
        failures.extend(f"taste catalog: {item}" for item in taste_summary.get("failures") or [])
    role_counts = _as_dict(payload.get("role_system_counts"))
    if role_counts.get("title") != 8:
        failures.append(f"title_system_count={role_counts.get('title')} expected=8")
    if int(role_counts.get("section") or 0) < 6:
        failures.append(f"section_system_count={role_counts.get('section')} expected>=6")
    if int(role_counts.get("evidence") or 0) < 8:
        failures.append(f"evidence_system_count={role_counts.get('evidence')} expected>=8")
    if int(role_counts.get("data") or 0) < 8:
        failures.append(f"data_system_count={role_counts.get('data')} expected>=8")
    if int(payload.get("narrative_arc_count") or 0) < 6:
        failures.append(f"narrative_arc_count={payload.get('narrative_arc_count')} expected>=6")
    return {
        "passed": not failures,
        "catalog_version": payload.get("catalog_version"),
        "grammar_count": len(records),
        "preset_count": len(preset_map),
        "max_presets_per_grammar": max(usage.values(), default=0),
        "unique_grammar_id_count": len(set(ids)),
        "unique_structural_signature_count": len(set(signatures)),
        "role_system_counts": role_counts,
        "narrative_arc_count": payload.get("narrative_arc_count"),
        "preset_to_grammar": preset_map,
        "failures": failures,
    }


def _score_record(record: dict[str, Any], *, text: str, style_preset: str) -> tuple[int, list[str]]:
    query_tokens = _tokens(text)
    score = 0
    reasons: list[str] = []
    presets = set(map(str, _as_list(record.get("style_presets"))))
    if style_preset and style_preset in presets:
        score += 100
        reasons.append("requested preset grammar")
    keyword_hits = query_tokens.intersection(_tokens(" ".join(map(str, record.get("prompt_keywords") or []))))
    if keyword_hits:
        score += min(24, len(keyword_hits) * 4)
        reasons.append("grammar terms: " + ", ".join(sorted(keyword_hits)[:5]))
    descriptor_hits = query_tokens.intersection(
        _tokens(" ".join([str(record.get("description") or ""), " ".join(map(str, record.get("best_for") or []))]))
    )
    if descriptor_hits:
        score += min(12, len(descriptor_hits) * 2)
        reasons.append("topic fit: " + ", ".join(sorted(descriptor_hits)[:5]))
    requested = _requested_variants(text)
    preferred = set(map(str, _as_list(record.get("preferred_variants"))))
    variant_hits = [variant for variant in requested if variant in preferred]
    if variant_hits:
        score += len(variant_hits) * 3
        reasons.append("requested shapes: " + ", ".join(variant_hits))
    return score, reasons


def route_composition_grammars(
    *,
    topic: str,
    user_prompt: str,
    style_preset: str = "",
    limit: int = 3,
    intake_answers: dict[str, str] | None = None,
) -> dict[str, Any]:
    answers = normalize_intake_answers(intake_answers)
    explicit_style = style_preset if style_preset != "auto" else ""
    answered_style = answers.get("style", "").lower()
    style_preset = explicit_style or (answered_style if answered_style in PRESET_TO_GRAMMAR else "")
    authoring_prompt = intake_authoring_prompt(user_prompt, answers, explicit_style=explicit_style)
    text = " ".join(part for part in [topic, authoring_prompt] if str(part or "").strip())
    scored: list[dict[str, Any]] = []
    for grammar_id in COMPOSITION_GRAMMARS:
        mapped_presets = COMPOSITION_GRAMMARS[grammar_id]["style_presets"]
        record_preset = style_preset if style_preset in mapped_presets else mapped_presets[0]
        record = _record_from_grammar(grammar_id, style_preset=record_preset)
        score, reasons = _score_record(record, text=text, style_preset=style_preset)
        record["route_score"] = score
        record["selection_reasons"] = reasons or ["stable catalog fallback"]
        scored.append(record)
    scored.sort(key=lambda item: (-int(item.get("route_score") or 0), str(item.get("grammar_id") or "")))
    locked_id = PRESET_TO_GRAMMAR.get(style_preset) if style_preset else None
    primary = next((record for record in scored if record.get("grammar_id") == locked_id), None)
    primary = primary or (scored[0] if scored else {})
    alternatives = [
        record
        for record in scored
        if record.get("grammar_id") != primary.get("grammar_id")
    ][: max(0, min(2, limit - 1))]
    return {
        "route_version": "composition_grammar_route_v1",
        "catalog_version": CATALOG_VERSION,
        "topic": topic,
        "user_prompt": user_prompt,
        "authoring_prompt": authoring_prompt,
        "intake_answers": answers,
        "explicit_style_preset": explicit_style,
        "style_preset_hint": style_preset,
        "requested_variants": _requested_variants(text),
        "primary": primary,
        "alternatives": alternatives,
        "selection_rule": (
            "Use primary as the deck grammar. Borrow isolated treatments only when the content shape benefits; "
            "never merge complete role systems or page systems."
        ),
    }


def _compact_record(record: dict[str, Any]) -> dict[str, Any]:
    keys = (
        "grammar_id", "style_preset", "style_presets", "family", "lane", "description",
        "rhythm_treatments", "rhythm_pattern", "role_variant_map", "preferred_variants",
        "renderer_bias", "renderer_role_systems_v1", "renderer_role_contracts_v2", "title_system_id", "section_system_id",
        "evidence_system_id", "comparison_system_id", "data_system_id", "decision_system_id",
        "references_system_id", "narrative_arc", "density", "grid", "reading_path",
        "preferred_role_variants", "invariant_moves", "forbidden_moves", "distinctive_moves",
        "avoid", "mix_rule", "max_consecutive_same_variant", "structural_signature",
        "route_score", "selection_reasons",
    )
    return {key: record.get(key) for key in keys if record.get(key) not in (None, [], {}, "")}


def compact_grammar_route(route: dict[str, Any]) -> dict[str, Any]:
    return {
        "route_version": route.get("route_version"),
        "catalog_version": route.get("catalog_version"),
        "topic": route.get("topic"),
        "user_prompt": route.get("user_prompt"),
        "authoring_prompt": route.get("authoring_prompt"),
        "intake_answers": route.get("intake_answers"),
        "explicit_style_preset": route.get("explicit_style_preset", route.get("style_preset_hint")),
        "style_preset_hint": route.get("style_preset_hint"),
        "requested_variants": route.get("requested_variants"),
        "primary": _compact_record(_as_dict(route.get("primary"))),
        "alternatives": [
            _compact_record(record)
            for record in _as_list(route.get("alternatives"))
            if isinstance(record, dict)
        ],
        "selection_rule": route.get("selection_rule"),
    }


_CAPABILITY_PATH = Path(__file__).resolve().parent.parent / "schemas" / "renderer_capabilities_v2.json"
_RENDERER_CAPABILITIES = json.loads(_CAPABILITY_PATH.read_text(encoding="utf-8"))
V2_ROLE_VARIANT_CANDIDATES = _RENDERER_CAPABILITIES["role_variants"]
FALLBACK_ROLE_VARIANT_CANDIDATES = _RENDERER_CAPABILITIES["fallback_role_variants"]


def _starter_sequence_for_candidate(candidate: dict[str, Any], slide_count: int) -> list[dict[str, Any]]:
    slide_count = max(3, min(30, slide_count))
    arc = _as_dict(candidate.get("narrative_arc"))
    stages = [str(value) for value in _as_list(arc.get("stages")) if str(value).strip()]
    role_map = _as_dict(candidate.get("role_variant_map"))

    def variant_for(role: str, fallback: str, map_key: str | None = None) -> str:
        supported = [str(value) for value in V2_ROLE_VARIANT_CANDIDATES.get(role, [])]
        requested = str(role_map.get(map_key or role) or "").strip()
        if requested in supported:
            return requested
        preferred = [
            str(value)
            for value in _as_list(candidate.get("preferred_variants"))
            if str(value) in supported
        ]
        if preferred:
            return preferred[0]
        return fallback if fallback in supported else supported[0]

    middle_blueprint = [
        ("evidence", variant_for("evidence", "stats"), "establish context and stakes"),
        ("chart", variant_for("chart", "chart", "data"), "show the decisive quantitative evidence"),
        ("comparison", variant_for("comparison", "comparison-2col"), "compare alternatives or tradeoffs"),
        ("decision", variant_for("decision", "matrix"), "state the recommendation and guardrails"),
        ("evidence", "timeline", "show implementation, ownership, or sequence"),
        ("evidence", "cards-2", "add one bounded proof or implication"),
        ("decision", "standard", "close an unresolved decision or action"),
    ]
    middle_count = max(1, slide_count - 2)
    selected = middle_blueprint[:middle_count]
    while len(selected) < middle_count:
        selected.append(middle_blueprint[(len(selected) - len(middle_blueprint)) % len(middle_blueprint)])
    sequence: list[dict[str, Any]] = [
        {
            "slide": 1,
            "role": "title",
            "variant": "title",
            "intent": stages[0] if stages else "governing question or answer",
        }
    ]
    for index, (role, variant, story_job) in enumerate(selected, start=2):
        stage_index = min(index - 1, max(0, len(stages) - 1))
        sequence.append(
            {
                "slide": index,
                "role": role,
                "variant": variant,
                "intent": stages[stage_index] if stages else story_job,
            }
        )
    sequence.append(
        {
            "slide": slide_count,
            "role": "references",
            "variant": "table",
            "intent": stages[-1] if stages else "sources and accountability",
        }
    )
    return sequence


def quick_deck_agent_brief(
    route: dict[str, Any],
    *,
    slide_count: int,
    agent_profile: str = "auto",
    intake_answers: dict[str, str] | None = None,
    remaining_percent: float | None = None,
    current_model: str | None = None,
    available_models: list[str] | None = None,
) -> dict[str, Any]:
    """Return the small normal-workflow handoff a model should reason over."""
    answers = normalize_intake_answers(intake_answers if intake_answers is not None else route.get("intake_answers"))
    if intake_answers is not None and answers != route.get("intake_answers", {}):
        route = route_composition_grammars(
            topic=str(route.get("topic") or ""),
            user_prompt=str(route.get("user_prompt") or ""),
            style_preset=str(route.get("explicit_style_preset", route.get("style_preset_hint")) or ""),
            intake_answers=answers,
        )
    primary = _as_dict(route.get("primary"))
    prompt = str(route.get("authoring_prompt") or route.get("user_prompt") or "").strip() or str(route.get("topic") or "")
    profile, basis = resolve_profile(agent_profile, prompt)
    if route.get("style_preset_hint"):
        answers["style"] = str(route["style_preset_hint"])
    intake = build_deck_intake(
        " ".join(str(value or "") for value in (route.get("topic"), route.get("user_prompt"))),
        answers=answers, remaining_percent=remaining_percent,
        current_model=current_model, available_models=available_models,
    )
    slide_count = max(3, min(30, slide_count))
    skill_root = Path(__file__).resolve().parent.parent
    runtime = skill_root / "scripts" / "python_runtime.py"
    entrypoint = skill_root / "scripts" / "present.py"
    readability_contract = {
        "min_title_pt": 28,
        "min_body_pt": 16,
        "min_support_pt": 13,
        "min_caption_pt": 9,
        "min_footer_pt": 9,
        "min_metadata_pt": 9,
        "max_title_lines": 2,
    }
    candidate_limit = {"fast": 1, "balanced": 2, "quality-first": 3}[profile]
    candidates = [primary, *_as_list(route.get("alternatives"))]
    if route.get("style_preset_hint"):
        candidates = [primary]
    route_candidates: list[dict[str, Any]] = []
    for candidate in candidates:
        if not isinstance(candidate, dict):
            continue
        if any(item["grammar_id"] == candidate.get("grammar_id") for item in route_candidates):
            continue
        candidate_arc = _as_dict(candidate.get("narrative_arc"))
        route_candidates.append(
            {
                "grammar_id": candidate.get("grammar_id"),
                "style_preset": candidate.get("style_preset"),
                "lane": candidate.get("lane"),
                "why": _as_list(candidate.get("selection_reasons"))[:1]
                or [candidate.get("description")],
                "story_shape": {
                    "stages": _as_list(candidate_arc.get("stages"))[:5],
                    "reading_path": _as_list(candidate.get("reading_path"))[:3],
                    "role_variants": _as_dict(candidate.get("role_variant_map")),
                    "must_do": _as_list(candidate.get("invariant_moves"))[:1],
                    "avoid": _as_list(candidate.get("forbidden_moves"))[:2],
                },
            }
        )
        if profile == "fast":
            route_candidates[-1]["starter_sequence"] = _starter_sequence_for_candidate(candidate, slide_count)
        if len(route_candidates) == candidate_limit:
            break
    visual_hints = select_visual_reference_hints(
        route_candidates, user_prompt=" ".join([str(route.get("topic") or ""), prompt]),
        content_shapes=_as_list(route.get("requested_variants")),
    )
    for candidate in route_candidates:
        candidate["visual_references"] = visual_hints.get(str(candidate.get("grammar_id") or ""), [])
    brief = {
        "schema_version": "quick_deck_agent_brief/v3",
        "topic": route.get("topic"),
        "user_request": route.get("user_prompt") or "",
        "agent_profile": profile,
        "intake": intake,
        "resolution_basis": basis,
        "profile_policy": "Local workflow defaults, not model performance guarantees; use an explicit profile for other models.",
        "agent_mode": "single-agent" if profile == "fast" else "single-agent-unless-independent-work-helps",
        "route_mode": "deterministic" if profile == "fast" else "model-select-from-bounded-candidates",
        "route_candidates": route_candidates,
        "visual_reference_policy": VISUAL_REFERENCE_POLICY,
        "fallback_route": {
            "style_preset": primary.get("style_preset"),
            "grammar_id": primary.get("grammar_id"),
        },
        "story_guidance": "Use only the chosen candidate's story hints. Derive slide order and evidence shapes from the argument, not a fixed template.",
        "requested_variants": route.get("requested_variants"),
        "renderer": {
            "role_variants": V2_ROLE_VARIANT_CANDIDATES,
            "fallback_role_variants": FALLBACK_ROLE_VARIANT_CANDIDATES,
            "layout_variants": ["primary", "alternate", "dense"],
            "suggestion_policy": "v2 geometry: role_variants. Supported fallback geometry: fallback_role_variants. Choose by evidence; fallback receipts do not claim v2 slot execution.",
        },
        "outline_contract": {
            "root_required": ["title", "deck_style", "slides"],
            "deck_style": {
                "style_preset": "copy from the chosen route candidate",
                "composition_grammar": "copy grammar_id from the same candidate",
                "style_seed": "<stable-topic-slug>",
                "header_variant": "auto",
                "footer_mode": "source-line",
                "footer_page_numbers": True,
                "readability_contract": readability_contract,
            },
            "slide_common": {
                "type": "title | content",
                "role": "editable structure from renderer.role_variants or fallback_role_variants",
                "variant": "supported variant for that role; prefer the actual evidence shape",
                "slide_intent": "topic-specific story job",
                "title": "assertion or governing question",
                "sources": ["stable source IDs such as S1"],
            },
            "payload_by_variant": {
                "title/section": ["title", "subtitle?", "kicker?"],
                "stats": ["facts: [{value: numeric KPI, label, detail?}]"],
                "cards-2/cards-3": ["cards: [{title, body}] (exactly 2 or 3 entries)"],
                "chart": ["chart: {type, categories, series: [{name, values}], facts?}"],
                "table": ["table: {headers, rows, column_weights?}"],
                "comparison-2col": ["left: {title, bullets}", "right: {title, bullets}"],
                "matrix": ["quadrants: exactly 4 {title, body} objects", "summary_callout?"],
                "standard": ["bullets: [text]"],
                "timeline": ["milestones: [{label, title, body}]"],
                "flow": ["flow_steps: 2-4 {title, detail?} stages for native editable methods; do not invent missing stages"],
                "image-sidebar": ["assets.hero_image: local slide-ready figure", "sidebar_sections: [{title, body}]", "caption?", "image_sidebar_mode: analysis-rail | evidence-mosaic | editorial-atlas"],
                "scientific-figure": ["figures: 1-4 {path, label?, title?, caption?} local panels", "figure_layout: panel-grid | primary-rail | ledger-rail | strip-readout", "figure_frame: open | ruled | panel", "interpretation?"],
                "lab-run-results": ["tables: [{title?, headers, rows, cell_styles?}]", "interpretation?"],
            },
            "content_limits": {
                "slides": slide_count,
                "facts": "2-4",
                "table": "prefer <=6 columns and <=7 rows",
                "timeline": "3-5 milestones",
            },
        },
        "authoring_rules": [
            "Choose a preset/grammar for audience and evidence. Honor style locks; fallback if uncertain.",
            "Story hints and starter_sequence are optional; let evidence determine the argument.",
            "Use supported role/variant pairs; prefer real figures, tables and native methods to generic cards.",
            "Lab: size evidence first, then interpretation/limits. Plot labels >=13pt at inserted size. Retain units, denominators and captions; no private data in public examples.",
            "At most two consecutive slides use the same concrete variant.",
            "Shorten or split before shrinking below readability floors.",
            "No invented evidence/citations; label synthetic data. Every profile needs QA and rendered review.",
            "Check values, units, denominators, caveats and sources against evidence. Layout QA is not fact checking.",
        ],
        "commands": {
            "finalize": (
                f"python3 {runtime} {entrypoint} finalize "
                "--outline <outline.json> --output <output.pptx> --qa-dir <qa-dir>"
            ),
            "repair_loop": "Read QA and renders, fix outline.json, rerun affected checks until clean or report a blocker.",
        },
    }
    if route.get("intake_answers"):
        brief["authoring_prompt"] = prompt
    if profile == "fast":
        brief["outline_contract"]["minimal_payload_examples"] = minimal_payload_examples()
        # Concrete examples already describe the v2 payloads; do not repeat them.
        examples = brief["outline_contract"]["minimal_payload_examples"]
        brief["outline_contract"]["payload_by_variant"] = {
            key: value for key, value in brief["outline_contract"]["payload_by_variant"].items()
            if not all(variant in examples for variant in key.split("/"))
        }
        brief["diagnostics"] = compact_authoring_diagnostics()
    return brief


def main() -> int:
    parser = argparse.ArgumentParser(description="Build or route the canonical composition-grammar catalog.")
    parser.add_argument("--summary", action="store_true", help="Validate and summarize the eight grammar routes.")
    parser.add_argument("--topic", default="")
    parser.add_argument("--user-prompt", default="")
    parser.add_argument("--style-preset", default="")
    parser.add_argument("--limit", type=int, default=3)
    parser.add_argument(
        "--agent-brief",
        action="store_true",
        help="Emit the compact normal-workflow handoff instead of full normalized contracts.",
    )
    parser.add_argument("--slide-count", type=int, default=7)
    parser.add_argument(
        "--agent-profile",
        default="auto",
        choices=sorted(PROFILE_ALIASES),
        help=PROFILE_HELP,
    )
    args = parser.parse_args()
    if args.summary or not (args.topic or args.user_prompt or args.style_preset):
        print(json.dumps(validate_composition_grammar_catalog(), indent=2, ensure_ascii=False))
        return 0
    route = route_composition_grammars(
        topic=args.topic,
        user_prompt=args.user_prompt,
        style_preset=args.style_preset,
        limit=max(1, min(3, args.limit)),
    )
    if args.agent_brief:
        print(
            json.dumps(
                quick_deck_agent_brief(
                    route,
                    slide_count=max(3, min(30, args.slide_count)),
                    agent_profile=args.agent_profile,
                ),
                indent=2,
                ensure_ascii=False,
            )
        )
        return 0
    print(json.dumps(compact_grammar_route(route), indent=2, ensure_ascii=False))
    return 0


if __name__ == "__main__":
    raise SystemExit(main())
canvas-designanthropics/skillsCreate beautiful visual art in .png and .pdf documents using design philosophy. You should use this skill when the user asks to create a poster, piece of art, design, or other static piece. Create original visual designs, never copying existing artists' work to avoid copyright violations.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
docxanthropics/skillsUse this skill whenever the user wants to create, read, edit, or manipulate Word documents (.docx files) or Word templates (.dotx files). Triggers include: any mention of 'Word doc', 'word document', '.docx', '.dotx', or requests to produce professional documents with formatting like tables of contents, headings, page numbers, or letterheads. Also use when extracting or reorganizing content from .docx or .dotx files, inserting or replacing images in documents, performing find-and-replace in Word files, working with tracked changes or comments, or converting content into a polished Word document. If the user asks for a 'report', 'memo', 'letter', 'template', or similar deliverable as a Word or .docx file, use this skill. Do NOT use for PDFs, spreadsheets, Google Docs, or general coding tasks unrelated to document generation.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
pdfanthropics/skillsUse this skill whenever the user wants to do anything with PDF files. This includes reading or extracting text/tables from PDFs, combining or merging multiple PDFs into one, splitting PDFs apart, rotating pages, adding watermarks, creating new PDFs, filling PDF forms, encrypting/decrypting PDFs, extracting images, and OCR on scanned PDFs to make them searchable. If the user mentions a .pdf file or asks to produce one, use this skill.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
pptxanthropics/skillsUse this skill any time a .pptx or .potx file is involved in any way — as input, output, or both. This includes: creating slide decks, pitch decks, or presentations; reading, parsing, or extracting text from any .pptx or .potx file (even if the extracted content will be used elsewhere, like in an email or summary); editing, modifying, or updating existing presentations; combining or splitting slide files; working with templates (.potx), layouts, speaker notes, or comments. Trigger whenever the user mentions "deck," "slides," "presentation," or references a .pptx or .potx filename, regardless of what they plan to do with the content afterward. If a .pptx or .potx file needs to be opened, created, or touched, use this skill.Stars: 197kUpdated Claude CodeCodexVerifiedInstall