# IQ Pages production workflow This is the authoritative operating contract for creating, updating and presenting IQ Pages content. It covers both scrolling pages and fixed-stage slide decks. ## Core model IQ Pages is the content system. A folder of source files is projected in one of two modes: - `mode: pages` (or omitted): a normal scrolling document with natural section heights. - `mode: slides`: a fixed-stage presentation with navigation, builds, chrome and morphs. Slides are therefore a presentation mode of IQ Pages, not a separate authoring system. Git is the source of truth. WorkDrive may synchronise the checkout between machines, but it does not replace Git branch, commit or remote-state checks. The primary local checkout currently remains `Z:\IU Ops Shared\IQ-Slides`. Hosted source is synchronised one way from GitHub `main` by the native Cloudflare Pages project `iq-slides-git` at `https://iq-slides-git.pages.dev/`. ## Folder contract Every production item lives under `decks//` and contains: ```text deck.json title, mode, stage, order and global tokens theme.css every folder-level visual rule slides/*.md concise content and frontmatter assets/ static images, data and generated research exports AGENTS.md item-specific voice, sources, refresh and QA rules index.html committed baked presenter output ``` Optional folders are `partials/` for included markdown and `templates/elements/` for reusable markup. A grouped example may live deeper, but every leaf deck name must remain lowercase and URL-safe. CLI commands accept either the full path or a unique leaf name. ## Authoring priority Use the smallest source representation that preserves the intended result: 1. Normal markdown and a supported slide type. 2. Shortcodes for reusable visual/data elements. 3. A named `variant` whose markup is generated by the renderer and styled by the folder theme. 4. Includes or templates for repeated local structures. 5. `type: raw` for genuinely bespoke HTML. HTML is allowed. The constraint is not “markdown only”; it is that routine updates should not require an agent to maintain hundreds of decorative tags or per-character spans. Complex markup belongs in the renderer, a reusable template, a shortcode, or a deliberately bespoke raw slide. Current house variants: - `type: hero` + `variant: technical-grid` - `type: bullets` + `variant: standard-text` For a complete page-to-slideshow example using one shared topic and evidence asset, see `docs/WORKFLOW-DEMO.md`. ## Automation and agent workflow For research, news and market updates: 1. Pull or fetch the latest Git state before editing. 2. Read the root and target-folder `AGENTS.md` files. 3. Gather approved research and record source URLs plus the as-at time. 4. Update markdown, structured data and static assets. Keep the core narrative independent of live embeds. 5. Leave concise hidden refresh instructions beside time-sensitive content: ```markdown ``` 6. Run `npm run present skip-open`. This deterministically bakes and validates the local presenter file that will be committed with the source. 7. Inspect the served source at desktop size and a narrow viewport when the layout changed. 8. Run `npm run build ` only when a portable one-file artefact is required. 9. Commit source files and the current `decks/.../index.html`. Do not commit `dist/`. 10. Run `npm run check` locally, inspect the result, then push to GitHub `main` through the normal review process. 11. Confirm the native Cloudflare Pages check succeeds for the pushed commit. No GitHub Action is involved; Cloudflare clones `main` and serves the repository root directly. When shared framework behaviour changes, run `npm run bake:all` before validation so every committed presenter file carries the same runtime. ## Presenter workflow The normal handoff is deliberately small: 1. Synchronise Git with `git pull --ff-only` (or the approved GUI equivalent). 2. Confirm the checkout is clean and its commit matches the intended GitHub commit. 3. Open `decks//index.html` directly. The agent should already have baked it. 4. Run `npm run present ` only when local source changed or an explicit rebake/validation check is wanted. Do not present from a checkout while another machine or agent is writing into the same synced folder. WorkDrive hydration and Git state should both be settled before opening the deck. ## Outputs | Output | Location | Purpose | Network expectation | |---|---|---|---| | Served source | `https://iq-slides-git.pages.dev/decks//` | Synced hosted page or slideshow | Local assets are static; live embeds still need network | | Baked presenter | `decks//index.html` | Committed local handoff after Git sync | Framework/content embedded; CSS/assets remain beside it | | Portable bundle | `dist/.html` | Optional email/iframe/single-file delivery | Static assets are embedded; live providers still need network | | Premium hosted output | Future vault-owned route | Member or client-only content | Must be gated at serving time and never publicly fetchable | The repository does not currently claim print/PDF as a production output. ## Public and premium serving During the current pre-user phase, Cloudflare serves the complete repository and the app and WordPress layers control normal discovery and presentation. This keeps GitHub-to-Cloudflare synchronisation immediate while agent and staff review remains the operating control. When user access and premium serving are introduced, premium output follows one rule: > Presenters render; the vault gates. Do not add authentication, PINs or membership state to this renderer. The future vault route checks identity/tier and then streams the appropriate output. Access hardening is deliberately deferred until that user-facing phase; it is not a prerequisite for the current native sync. ## Release checks Use these from the repo root: ```bash npm run validate # one source + bake npm run present skip-open # bake + validate one presenter output npm run build # optional portable bundle npm run bake:all # after shared runtime changes npm run catalogue # regenerate root deck catalogue npm run check # complete repository production check ``` A production handoff is complete only when source, baked output, Git state and the relevant rendered views agree. GitHub Actions is intentionally disabled for this repository. Do not recreate an automatic push/PR workflow unless the owner explicitly reverses that decision. Native Cloudflare Pages Git integration is active and is the hosted deployment owner; local validation remains mandatory for the agent or operator making the change.