# Spreads: start here

Spreads answers **how to present an argument visually**. Its examples also explain the communication job, evidence and surrounding narrative a composition needs. Logic Poetry owns the methods for discovering the **what and why**; exchange that argument at the methodology level, then choose its presentation here.

## Quick use

Read [AGENTS.md](AGENTS.md), establish the brief below, then search [ai-catalogue.json](ai-catalogue.json). Shortlist by the audience change and reasoning relationship. Load only the exact selected records from [semantic-matching.json](semantic-matching.json), their metadata and HTML. Read [SEMANTICS.md](SEMANTICS.md) for how to interpret them.

If only this page is available, do not pretend to have inspected a layout. Ask for the selected files or use the [public gallery](https://tdw-spreads.choiceoak6.chatgpt.site/) and its **Use with AI** prompt. Repository permission and an AI connector's access are separate.

## Work on an editable storyboard

**AI-driven local pilot:** when the `spreads` MCP server is configured in Codex, use `sp_guide`, `sp_search`, `sp_state` and `sp_asset` to retrieve this method and the exact composition. Read the workflow skill returned by `sp_guide`. Codex uses its own reasoning and native document tools to build a new review copy; the library server neither generates decks nor receives local deck files. `sp_check_plan` applies the same structural checks as the optional workbench. Ask only for missing inputs; do the mapping, application and rendered review within the user's scope.

The [proposal workbench](workbench/index.html) is an optional browser-based pilot for Build and Debug. [Its guide and plan contract](workbench/README.md) explain save/reopen, structural checks and AI handoff. Keep private plans in the destination project, outside this repository. The workbench does not generate a native deck or establish semantic or visual correctness.

## 1. Establish a useful brief

Write one sentence: **We need [audience], who currently [understanding], to [decision/action], using [available support], in [medium and context].**

Capture the project, audience, desired outcome, known facts, assumptions, necessary qualifications, brand, language, output format and time/length constraints. For decks, distinguish narrated presentation from a document read alone. Preserve approved creative, intentional blanks and other locked material. Infer known inputs; avoid asking the user to repeat them.

If the proposition or supporting logic is missing, surface that gap. Use the project's strategy method to resolve it. Do not invent a strategy to fit an attractive template.

## 2. Route the task

| Task | Read/use | Produce |
|---|---|---|
| Find a composition for one point | `ai-catalogue.json` → exact matching record → selected HTML | A recommendation, why it fits, required inputs and a preview |
| Assemble a deck or article | Brief → argument/title spine → selected states | A minimal coherent sequence with the before/after dependency of every unit |
| Improve or replace a slide | Original purpose + surrounding passage → alternative state contracts | Options with evidence requirements, gain/loss, pacing and transition edits |
| Select artwork or compose words and images | [Artwork and layout](artwork-and-layout.md) → composition brief → selected state and actual asset | Complementary copy/image meaning, a planned frame, editable native composition and reviewed combined render |
| Adapt a reviewed example | `cases/index.json` → teaching page → `case.json` + `reuse.json` | New content in a faithful reasoning structure, with missing facts visible |
| Native PowerPoint | Selected composition + the destination project's PowerPoint method | An actual `.pptx`, editable where promised, rendered and inspected |
| Web/editorial composition | Selected HTML and its CSS/JS/assets + destination design system | A responsive component with reading order, motion and fallback verified |
| Extend this library | `AUTHORING.md`, `SEMANTICS.md`, `reuse-policy.md` | Reviewed option or distinct arrangement with version-bound records |

## 3. Resolve the exact files

- `spreads.json`: 98 parent layouts, their options and semantic profiles.
- `ai-catalogue.json`: compact discovery index for all 241 states (98 defaults + 143 variations). Its `known_limits` and `recommendation_eligible` are part of the contract.
- `semantic-matching.json`: detailed state records. IDs use `S25--audience-journey`, for example.
- `<layout-dir>/spread.json`: parent metadata. Merge `semantic.variations[option]` over the base for the selected use; do not inherit the base's worked example accidentally.
- Most options use `<layout-dir>/spread.html?opt=<option>&surface=<surface>`. Default omits `opt`.
- **If `options[].files` or the matching record's `files` exists, use `files.html` instead.** Those paths are relative to the library root. The four new teaching options use independently scoped markup under `cases/`; appending their names to parent HTML will not select them.
- Resolve CSS, scripts, fonts and image references relative to the selected HTML. Keep required licences/credits when copying assets.
- `case.json` stores the reviewed meaning, slots and fictional example. `reuse.json` stores tested counts, conditional alternatives and format limits. Parent group slots can contain child slots; do not count both as independent content.
- `semantic-coverage.json` records the earlier 231-state review. `case-batch-review.json` and `batch-01-integration.json` cover the four added states. `release-review.json` records release integration checks. These scopes are not interchangeable.

## 4. Select for meaning, then fit

For each candidate, check:

1. **Question and change:** what does the audience understand before and after?
2. **Relationship:** comparison, sequence, hierarchy, cause, evidence, synthesis, choice or another explicit relation. Reject a mismatch even if the boxes look right.
3. **Support:** does the input supply the evidence, units, denominators, qualifications and decision criteria required?
4. **Slots:** map every required region to its communication role. Use the actual selected markup, including unannotated peers called out in metadata.
5. **Counts:** distinguish the logical repeatable group from this rendered instance. Three can become four when the relationship survives. State which count has been checked.
6. **Flow:** what must already be established, and what question/action does this prepare? A replacement may need two slides instead of one.
7. **Format:** does the composition work at the target size, reading distance and interaction mode?

For alternatives, describe the different route to a similar audience outcome, the extra evidence it needs, what improves or is lost and changes to both transitions. Mark alternatives as observed, inferred or tested. Similar labels such as “insight” or “reassurance” do not establish interchangeability.

Before filling an image region, use the canonical [artwork-and-layout workflow and reusable brief](artwork-and-layout.md#reusable-composition-and-image-generation-brief). Plan what the image adds to the copy, compose the frame first, then review the actual image and layout together. Artwork is one possible medium; neither an empty slot nor a library sample is a requirement to generate an image or inherit its aesthetic.

## 5. Build the audience journey

Use a provisional route such as **context → tension → insight/reframe → creative reveal → why it works → plan → execution/decision** only when the argument warrants it. This is a planning aid, not a corpus-proven universal sequence. An evidence-led executive decision may need its recommendation upfront instead.

Treat the deck as linked audience encounters. Every unit needs a point, substance and an ending that lands or prepares the next question. A visual can perform any of these functions without a separate text block. Make cycles, comparisons and causal relationships visible. Preserve surprise where a creative reveal earns it; a slogan deserves space when it is the reveal.

Whole-corpus frequency analysis, an optimal-route recommender and a universal master sequence remain future work. Do not claim that popularity or a respected source proves a route will persuade this audience.

## 6. Reviewed teaching cases

| State | Audience job | Checked instance |
|---|---|---|
| S25--audience-journey | Map changing audience readiness to suitable invitations and activities | Four stages |
| S25--story-planning | Turn one theme into distinct publishable stories with support | Three and four angles; use the matching HTML and case record |
| S70--activation-detail | Explain how an experience works and what delivery needs | One experience with supporting visual regions |
| S11--treatment-comparison | Compare visual directions for the same proposition | Two genuinely different compositions with matched copy and images |
| S06--shared-consequence | Reframe an individual action through its consequence for another person | Three fixed reasoning roles |
| S41--capability-to-purpose | Connect capabilities to purposes through explicit mechanisms | Three and four pairs |
| S58--response-gate | Apply a criterion before choosing a response method | Two fixed outcomes; two and three methods inside Yes |
| S79--scarcity-and-demand | Find a qualitative gap worth investigating | Four and five offerings; no invented numerical coordinates |
| S77--preparation-before-delivery | Separate readiness, delivery and continuous support | Three and four workstreams across three ordinal phases |
| S40--bounded-scope | Make included and separately quoted work explicit | Four and five scope rows |

Browse [the teaching cases](cases/index.html). Choose the jobs your argument needs; the catalogue is not a mandatory pitch sequence. All are static editable HTML; a reusable native PowerPoint master is not supplied in this release. Follow each selected state's explicit `files` paths, including `alternate_html` and `alternate_case` where present. [Batch 2 review](batch-02-review.json) records the six latest cases' render and gallery checks.

## 7. Deliver a concrete recommendation

Keep the user's first view short. Supply:

- Exact code/option and why it fits this audience change.
- Input-to-slot mapping, missing support and actual item count.
- Previous → this → next argument, including the closing handoff.
- Editable artifact in the requested destination and format.
- What was tested, remaining limits and one next step if needed.

Use [CHECKLIST.md](CHECKLIST.md). The human curates the idea; the agent does the mapping, building and checking within the authorised task.

## Connection boundary

An AI can read these files from a clone, attachments, GitHub connector or public URLs. The source checkout now includes a local Codex MCP pilot, separately installed on the owner's Mac. Visiting the site or sharing this repository does not install it in another host. It exposes eligible catalogue discovery, selected state/source/assets and structural plan checks, without private source bridges. Search is lexical discovery interpreted by the calling AI, not a trained semantic ranking service. Native deck application depends on the host's tools and must be tested for each output; library HTML checks do not certify all PowerPoint adaptations.