@pikaa-ai/pikaa 0.3.1 → 0.3.4

package/skills/pptx-posters/references/poster_content_guide.md

@@ -1,176 +0,0 @@
-# Source-bound poster content
-
-## Non-negotiable rule
-
-The generator renders approved manifest content. It does not research, infer, draft,
-summarize, complete, or "improve" scientific claims. Never invent poster text,
-citations, data, statistics, author details, affiliations, funding statements, image
-licenses, or QR destinations.
-
-If an exact source or author approval is missing, stop. Keep the manifest in `draft`
-status. Do not replace missing material with plausible prose.
-
-## Build an evidence packet first
-
-Ask the author for the local, authoritative material needed for this poster:
-
-- accepted abstract or author-approved summary;
-- exact title, author order, affiliations, contact details, and identifiers;
-- final tables, figures, captions, units, sample sizes, statistics, and uncertainty;
-- bibliography or exact publication identifiers;
-- funding, conflict, ethics, registration, data, and code statements where applicable;
-- optional local logos and images plus provenance and ownership/license/permission
-  records;
-- organizer poster instructions and printer specifications;
-- exact QR destination and the visible fallback URL/text.
-
-Record each item as a `sources[]` entry with a unique ID. A locator can be a DOI,
-stable URL, local controlled-record identifier, figure/table number, page/section,
-or dated author instruction. The scripts never dereference it.
-
-`author_verified: true` means a human author checked that source record. It does not
-mean an agent found a plausible web page.
-
-## Exact source IDs
-
-Every text or image element has `source_ids`. These IDs must exactly match records in
-`sources[]`; fuzzy title matching is forbidden.
-
-Use the smallest defensible source set:
-
-- a title/author element can cite the accepted-submission or author-roster record;
-- a result sentence should cite the exact table, figure, analysis output, or
-  publication location supporting it;
-- a figure should cite its data/figure provenance and its asset-license record;
-- a conference dimension should cite the organizer's current instruction;
-- a printer constraint should cite the current quote, specification, or written
-  confirmation.
-
-The validator rejects unknown and unused source IDs. This catches misspellings and
-stale records instead of guessing what the author meant.
-
-## Content selection is author-controlled
-
-There is no universal section list, word count, visual percentage, number of figures,
-or citation count. Use the organizer's requirements and the research story.
-
-A useful author review asks:
-
-1. What question should a viewer understand?
-2. Which exact result supports the take-home message?
-3. Which method detail is necessary to interpret that result?
-4. Which limitation prevents overstatement?
-5. What action or follow-up should the viewer take?
-
-Possible sections include context, objective, methods, results, limitations,
-conclusions, references, acknowledgments, and contact information. Include only those
-that are supported and appropriate. Clinical, qualitative, engineering, humanities,
-and computational posters often need different structures.
-
-## Preserve scientific meaning
-
-For each candidate edit:
-
-- preserve direction, magnitude, units, denominators, uncertainty, and qualifiers;
-- distinguish observed association from causation;
-- retain negative/null results when necessary to prevent a misleading summary;
-- keep population, intervention, comparator, endpoint, and time frame where relevant;
-- do not convert a model metric into a clinical or practical claim;
-- do not add significance language that the source does not support;
-- do not remove limitations that materially change interpretation;
-- define acronyms for the intended audience;
-- keep citation labels synchronized with the exact bibliography.
-
-An agent may propose shorter wording, but the author must approve the exact resulting
-text and renew the manifest content hash.
-
-## Figures and data
-
-Figures are optional. Use author-supplied local assets or assets generated separately
-from exact author data in a reviewed workflow. This skill makes no network or model
-calls. Do not create substitute data, redraw values from memory, or ask an image model
-to depict scientific results.
-
-Before approval, verify:
-
-- values, labels, units, error definitions, sample sizes, and statistical notation;
-- category order, axes, scales, transformations, baselines, and truncation;
-- correspondence between caption and plotted data;
-- direct labels or a clear legend;
-- redundant encoding beyond color;
-- asset hash, source ID, exact provenance, license/permission, and concise alt text;
-- a source-bound native long description when alt text and adjacent prose are
-  insufficient for a complex figure;
-- final effective DPI for raster assets.
-
-If a chart must be regenerated, regenerate it from the author's exact data using a
-separate, reviewed analysis workflow. Record the tool/version or controlled workflow,
-input source IDs, date, human reviewer, and permission to use the output. Then add the
-resulting local image and provenance to the manifest.
-
-## Citations and references
-
-Copy citations only from the author's verified bibliography or primary source record.
-Never fabricate missing metadata. Keep identifiers exact, including DOI capitalization
-and version/date where those distinguish records.
-
-Space pressure does not justify an ambiguous citation. If the organizer permits a
-short display form, keep a stable identifier and provide an exact accessible full-list
-destination. The visible poster still needs enough information for a viewer to
-identify the source without relying solely on a QR code.
-
-## QR codes
-
-A QR image is only a local asset. The scripts do not generate it, resolve it, follow
-it, or create a hyperlink.
-
-For every QR asset:
-
-- record one exact `https://` target in `asset.qr_target`;
-- provide a separate text element with role `qr_fallback`;
-- include that exact URL verbatim in the fallback text;
-- cite the same source record from the image and fallback text;
-- write alt text that states the QR code's purpose and destination;
-- test the exported and printed code manually on multiple devices.
-
-Do not use a QR code as the only way to access essential poster content.
-
-## Approval binding
-
-Approval is content-specific:
-
-1. Complete the manifest with local assets and all exact source IDs.
-2. Keep `approval.status` as `draft`.
-3. Run the validator with `--print-content-hash`.
-4. Give the exact manifest and reported hash to the approving author.
-5. After approval, set `status`, `approved_by`, `approved_at`, and
-   `content_sha256`.
-6. Run normal validation and generation.
-
-Any change outside `approval` changes the canonical hash. The validator then refuses
-generation until an author approves the new hash.
-
-## Placeholder policy
-
-The bundled template intentionally contains replacement tokens, false confirmations,
-and draft approval. It must fail validation.
-
-The validator rejects common placeholder forms such as TODO, TBD, Lorem ipsum,
-REPLACE_ME, generic bracketed fields, and unresolved template labels. Do not weaken
-this policy to make a draft generate. Replace every field with reviewed content or
-stop.
-
-## Final content review
-
-Before release, the presenting/corresponding author should compare the poster against
-the original evidence packet and check:
-
-- title, author order, affiliations, correspondence, and funding;
-- every claim, number, unit, citation, image, and caption;
-- methods and limitations needed for valid interpretation;
-- consistency between poster text and figures;
-- accessibility text, visible QR fallbacks, and meaningful contact information;
-- conference and printer compliance;
-- the final manifest hash and generated PPTX hash.
-
-An automated pass never substitutes for scientific sign-off.

package/skills/pptx-posters/references/poster_design_principles.md

@@ -1,226 +0,0 @@
-# Poster design and accessibility principles
-
-## Requirements outrank conventions
-
-There is no universal poster size, orientation, grid, body font, margin, image DPI,
-word count, or number of columns. Confirm the current organizer and printer rules,
-record exact source IDs, and design against those constraints.
-
-Use generic advice only as a labeled project heuristic. Do not transform a heuristic
-into a conference or accessibility requirement.
-
-## Visual hierarchy
-
-Make the research question, key result, and interpretation easy to locate without
-forcing every poster into one visual style.
-
-- Use a small, consistent set of text roles.
-- Prefer left-aligned body text for left-to-right languages unless language or design
-  requirements indicate otherwise.
-- Keep related evidence, caption, and interpretation spatially grouped.
-- Use spacing, alignment, size, and weight before adding decorative effects.
-- Avoid unexplained icons, dense backgrounds, and text over uncontrolled imagery.
-- Do not rely on a predicted "eye pattern"; confirm the actual reading order.
-
-The generated PPTX uses fixed font sizes and disables text auto-shrink. A visual check
-is still required because the XML package does not reveal font substitution or
-rendered overflow.
-
-## Font size means final-output size
-
-PowerPoint stores point sizes on the PPTX canvas. When the printer scales the canvas,
-the physical text scales too:
-
-`final point size = design point size × physical artboard width / canvas width`
-
-Use the same ratio on height; unequal ratios are prohibited.
-
-Microsoft's PowerPoint accessibility guidance recommends 18 pt or larger for ordinary
-slides. That is a [Microsoft slide recommendation](https://support.microsoft.com/en-us/office/make-your-powerpoint-presentations-accessible-to-people-with-disabilities-6f7772b2-2f33-4bd2-8ca7-dae3b2b3ef25),
-not a universal poster minimum. Poster viewing distance, typeface, substrate, lighting,
-audience, and organizer rules can require larger text.
-
-The manifest therefore requires:
-
-- a final-output minimum;
-- a basis labeled `heuristic`, `source_specific`,
-  `conference_requirement`, or `printer_requirement`;
-- an exact source ID for every non-heuristic basis.
-
-Test a reduced-scale print and the full-size proof under expected viewing conditions.
-
-## Font availability and substitution
-
-A typeface name in PresentationML is a request, not proof that the font is installed,
-licensed for embedding, or rendered identically by another workstation. Microsoft's
-[font-embedding guidance](https://support.microsoft.com/en-us/office/benefits-of-embedding-custom-fonts-cb3982aa-ea76-4323-b008-86670f222dbc)
-notes that embedding can preserve layout but that not every font permits it and that
-embedding only used characters limits editing.
-
-The generator does not install or embed fonts. Before release:
-
-- use fonts licensed for the intended authoring, sharing, embedding, and print use;
-- confirm every declared face is installed on the review/export workstation;
-- inspect substitutions, missing glyphs, equations, and line wrapping in PowerPoint;
-- decide with the printer whether embedding is appropriate and permitted;
-- inspect the actual exported PDF's font records and rendered glyphs.
-
-## Text contrast
-
-[WCAG 2.2 SC 1.4.3](https://www.w3.org/TR/WCAG22/#contrast-minimum) specifies:
-
-- 4.5:1 for normal text;
-- 3:1 for large text, defined as at least 18 pt, or at least 14 pt and bold.
-
-WCAG is written for web content. This skill uses its sRGB contrast mathematics and
-thresholds as an explicit design target for poster/PPTX color pairs; a passing ratio
-does not by itself establish that a physical poster or exported PDF conforms to WCAG.
-Print conversion, transparency, gradients, images behind text, paper, glare, and
-lighting require manual review and proofing.
-
-The manifest declares each foreground/background pair and its usage. Text elements
-must reference a declared pair. The validator rejects a pair below its declared
-threshold.
-
-## Non-text contrast and color redundancy
-
-[WCAG 2.2 SC 1.4.11](https://www.w3.org/TR/WCAG22/#non-text-contrast) uses 3:1
-against adjacent colors for graphical parts required to understand content.
-[SC 1.4.1](https://www.w3.org/TR/WCAG22/#use-of-color) says color must not be
-the only visual means of conveying information.
-
-For plots and diagrams:
-
-- directly label important series and regions when practical;
-- combine color with shape, marker, pattern, line style, position, or text;
-- retain meaningful distinctions in grayscale;
-- avoid assigning semantic meaning to a hue without another cue;
-- check the rendered figure, not just the palette's color list.
-
-The palette checker reports exact pair ratios and heuristic grayscale L* separation.
-It explicitly does not certify color-vision accessibility.
-
-## Choosing palettes
-
-[ColorBrewer](https://colorbrewer2.org/) separates qualitative, sequential, and
-diverging schemes and provides filters for colorblind-safe, print-friendly, and
-photocopy-safe options. Its palettes were designed for maps; use the data-type logic,
-then test the actual poster figure and background.
-
-[Paul Tol's colour-scheme technical note](https://sronpersonalpages.nl/~pault/data/colourschemes.pdf)
-provides schemes intended to remain clear for color-blind readers. Choose a scheme
-for its documented purpose and supported category count. Do not assume every color
-in a named scheme has sufficient text or line contrast against white.
-
-Palette provenance does not replace contrast checks, redundant encodings, color-vision
-simulation, or print proofing.
-
-## Alt text and native text
-
-Microsoft says visuals need concise alternative text describing their purpose and
-important content. See
-[Make PowerPoint presentations accessible](https://support.microsoft.com/en-us/office/make-your-powerpoint-presentations-accessible-to-people-with-disabilities-6f7772b2-2f33-4bd2-8ca7-dae3b2b3ef25).
-
-This generator requires approved alt text for every local picture and writes it to
-the standard PresentationML nonvisual drawing description. The technical inspector
-checks that the description exists. It also supports a source-bound native text
-element as a long description for a complex figure.
-
-Alt text still needs human review:
-
-- describe the purpose and essential conclusion, not every pixel;
-- avoid repeating adjacent text verbatim;
-- do not begin with redundant phrases such as "image of";
-- include essential values and relationships when they are not available in nearby
-  native text;
-- keep important words as native PowerPoint text rather than only inside a raster
-  image.
-
-When concise alt text and adjacent prose do not communicate a figure's essential
-relationships, values, uncertainty, and conclusion, set
-`long_description_element_id` to an approved native body/caption/other text element.
-It must follow the image in reading order and cite every source used by the image.
-The structural check cannot determine whether the long description is scientifically
-or semantically complete.
-
-An XML attribute being present does not prove that the description is accurate.
-
-## Reading order
-
-Screen readers use an object's reading order, which can differ from its visual
-position. Microsoft recommends the Accessibility Checker and Reading Order pane.
-
-The manifest requires the visible title first, then contiguous `reading_order` values.
-The generator uses a native title placeholder, adds remaining shapes in that order,
-and writes explicit language on text runs. This is only a deterministic starting
-point. In the final PowerPoint:
-
-1. run Review > Check Accessibility;
-2. inspect the Reading Order pane;
-3. verify every object name and sequence;
-4. navigate with a keyboard;
-5. test with a screen reader.
-
-Groups, charts, SmartArt, decorative objects, and exported PDF tags need separate
-manual review. The strict generator intentionally limits its shape set to native text
-boxes and local pictures.
-
-## QR codes and links
-
-A QR code is not an accessibility substitute.
-
-- Include the exact destination URL as visible native text.
-- Use meaningful surrounding language that describes the destination.
-- Add alt text to the QR image.
-- Keep the fallback text in logical reading order.
-- Test the final exported/printed code with multiple devices.
-- Do not put essential content only behind the QR destination.
-
-The generator does not create a clickable external relationship. This allows the
-package inspector to reject all external relationships consistently.
-
-## Raster quality
-
-File metadata DPI does not determine poster quality. Use effective DPI:
-
-`effective DPI = source pixels / final placed inches`
-
-Calculate it independently for width and height at the final physical output. The
-asset inventory reports the lower value. The threshold must be labeled as a heuristic
-or tied to the exact organizer/printer/source rule.
-
-PowerPoint can compress inserted pictures. Microsoft documents High fidelity and
-per-document "Do not compress images in file" settings. Review those settings in the
-actual export application, then inspect the PDF and proof for resampling; the source
-PPTX effective-DPI calculation does not prove export resolution.
-
-Vector artwork may be preferable for line art, but this strict generator accepts only
-bounded local PNG/JPEG assets. If vector content is required, convert it through an
-author-reviewed, offline workflow and verify the rasterized result and text
-accessibility; do not silently substitute or redraw scientific content.
-
-## Audio, video, and linked media
-
-PowerPoint supports audio and video, including formats and linked-file workflows that
-vary by version. None is needed for a static printed poster. The strict manifest and
-package profile therefore allow only local PNG/JPEG still images and reject audio,
-video, linked media, transitions, timing, and other interactive content. Put optional
-external material behind a visible, verified URL/QR fallback rather than embedding or
-linking media in the PPTX.
-
-## Manual accessibility gate
-
-Before release:
-
-- run PowerPoint's Accessibility Checker;
-- verify reading order and object names;
-- review every alt text and native long description;
-- test screen-reader and keyboard navigation;
-- inspect text contrast, non-text contrast, and redundant encoding;
-- review reduced-scale and full-size proofs;
-- verify exported PDF tags and reading order;
-- test visible fallback links and QR codes;
-- get author and accessibility-reviewer sign-off.
-
-Automation finds technical defects. It cannot certify accessibility or scientific
-accuracy.

package/skills/pptx-posters/references/poster_layout_design.md

@@ -1,189 +0,0 @@
-# PowerPoint poster dimensions, layout, and output
-
-## Keep six concepts separate
-
-1. **Physical trim size** — finished width and height after cutting.
-2. **Bleed** — artwork extending beyond each trim edge when the printer requires it.
-3. **Physical artboard** — trim plus bleed on both sides:
-   `artboard = trim + 2 × bleed`.
-4. **Safe margin** — inset inside the trim edge for non-bleed content.
-5. **PowerPoint canvas** — the slide width and height stored in the PPTX.
-6. **Print/export scale** — uniform conversion from canvas to physical artboard.
-
-Raster effective DPI and final font size depend on physical placement, not merely the
-canvas.
-
-## Current PowerPoint size limits
-
-[Microsoft's current slide-size guidance](https://support.microsoft.com/en-us/office/change-the-size-of-your-powerpoint-slides-040a811c-be43-40b9-8d04-0de5ed79987e)
-states that each custom dimension is from 1 to 56 inches (2.54–142.24 cm). It also
-states that all slides in a presentation have the same size.
-
-Do not bypass this limit by supplying pixel values; PowerPoint converts entered units.
-This skill accepts inches and enforces the 1–56 inch range.
-
-If a required physical artboard exceeds 56 inches on an edge:
-
-- choose a smaller proportional canvas;
-- preserve the exact artboard aspect ratio;
-- record the uniform output scale;
-- confirm that the printer permits scaling;
-- scale design fonts so their final point sizes remain correct;
-- calculate image DPI at final physical placement.
-
-Do not scale width and height independently.
-
-## Scale equations
-
-For a proportional design:
-
-```text
-scale_x = physical_artboard_width / canvas_width
-scale_y = physical_artboard_height / canvas_height
-scale_x must equal scale_y
-
-final_font_pt = design_font_pt × scale
-final_placed_width_in = design_width_in × scale
-effective_dpi_x = image_width_px / final_placed_width_in
-```
-
-The manifest validator allows only a small numerical tolerance between `scale_x` and
-`scale_y`.
-
-## Bleed and safe area
-
-Bleed and safe margin are printer-specific. A conference board dimension does not
-establish either.
-
-The manifest treats the physical artboard, including bleed, as the area mapped to the
-PowerPoint canvas. It computes the safe inset on the canvas as:
-
-`(bleed + safe margin) / print scale`
-
-Native text must remain inside that boundary. Only intentional imagery may set
-`allow_in_bleed: true`.
-
-PowerPoint generation is not a press-ready preflight. The printer must confirm crop,
-trim, bleed, substrate, and proofing behavior.
-
-## Conference examples show variation
-
-These are dated examples, not presets:
-
-- [CSCW 2026](https://cscw.acm.org/2026/posters.html) allocated a 48 × 48 inch
-  space, recommended no more than 45 inches on either side, allowed up to 47 inches,
-  and said A0 or A1 could be acceptable.
-- [IEEE DSC 2025](https://attend.ieee.org/dsc-2025/call-for-posters/) required
-  posters to fit an A1 space (84.1 × 59.4 cm).
-
-The differences are the point: check the current instruction for the actual event.
-Board size, maximum poster size, submission-document format, and physical print size
-can be different rules.
-
-## Choosing a layout
-
-Choose a grid after content, orientation, language direction, and required dimensions
-are known.
-
-- A single narrative path can use one broad column or a sequence of panels.
-- Two columns can work for comparisons or smaller formats.
-- Three or more columns can shorten lines on wide canvases but increase navigation
-  complexity.
-- An asymmetric grid can emphasize one key result if the reading order remains clear.
-
-No column count is inherently standard or accessible. Use consistent alignment and
-spacing, and leave enough room for the actual approved content without shrinking type.
-
-The strict manifest places every text or image element in an explicit rectangle.
-Elements are listed in contiguous reading order and are generated in that order.
-
-## Bounds and overlap
-
-The layout checker reads PresentationML transforms directly. It reports:
-
-- shapes outside the slide;
-- direct bounding-box intersections;
-- text without explicit size;
-- text below the manifest's final-output minimum;
-- direct shape order and, when a manifest is supplied, exact object-name/order
-  comparison against approved `reading_order`.
-
-Bounding boxes are conservative. A report can include an intentional overlay, while
-a clean report can still hide text overflow, rotation, group-transform, chart, SmartArt,
-or font-substitution problems. The generator avoids groups, charts, SmartArt, and
-overlays so that a clean direct-box check is meaningful.
-
-Always inspect in PowerPoint and in the exported PDF.
-
-## Images
-
-Image placement uses `contain` fitting:
-
-- preserve the source aspect ratio;
-- center the image inside its approved element box;
-- do not crop or stretch;
-- use final placed dimensions for effective DPI.
-
-If the scientific message depends on a crop, create and approve a new local asset,
-hash it, and update its source/alt text. Do not apply a silent crop during generation.
-
-QR placement boxes must be square. Test the final physical QR code; pixel count and
-box geometry do not guarantee scan reliability.
-
-## Color mode
-
-Treat PowerPoint as an RGB authoring workflow. Its documented automation color
-property is RGB, and the generated package uses opaque sRGB hex colors.
-
-If the printer accepts RGB, record that requirement and approve a proof. If the
-printer manages conversion, obtain its profile/process and approve a proof. If the
-printer requires CMYK, the export plan blocks a claim of readiness until a
-printer-approved conversion and proof are complete. Do not label a native PowerPoint
-PDF as CMYK-compliant without verifying the actual output.
-
-Transparency, gradients, photographs, and institutional colors can change during
-conversion. Contrast calculations on source sRGB values do not predict the printed
-result.
-
-## PDF export
-
-[Microsoft's export guidance](https://support.microsoft.com/en-us/powerpoint/export-a-presentation)
-distinguishes Standard quality for publishing/printing from Minimum size. Use the
-current PowerPoint interface and Standard/high print quality when PDF is required.
-
-After export, independently verify:
-
-- PDF page/artboard dimensions and orientation;
-- one-page output when the organizer expects one page;
-- trim/bleed handling;
-- fonts, glyphs, equations, clipping, and substitutions;
-- image quality and resampling;
-- color and printer proof;
-- tags, reading order, alt text, links, and language;
-- conference naming, file-size, and upload requirements.
-
-[Microsoft's PowerPoint PDF accessibility documentation](https://learn.microsoft.com/en-us/office/pdf/powerpoint/powerpointpdfaccessibility)
-describes modern tagged-PDF behavior, but availability varies by PowerPoint version
-and channel. Verify the installed version and the actual PDF; do not infer PDF
-accessibility from the PPTX.
-
-## Resizing existing content
-
-Microsoft presents **Maximize** and **Ensure Fit** when changing slide size. Maximize
-can move content outside the slide; Ensure Fit can make content smaller.
-
-This workflow sets dimensions before adding content and does not repurpose an existing
-slide. If a human later changes the size, treat that as a layout change:
-
-1. re-check physical/canvas aspect and print scale;
-2. re-check every final font size and effective DPI;
-3. re-run bounds and overlap checks;
-4. renew author approval because layout and possibly content hash changed;
-5. re-export and re-proof.
-
-## Final physical review
-
-Inspect a reduced-scale proof and the printer's full-size or contract proof. Confirm
-readability at expected distances, trim, bleed, margins, color, raster quality, QR
-function, mounting constraints, and accessibility. No XML or geometry checker can
-simulate the final venue.