code/cl8y-docs
5
0
Fork 1
Code Issues 8 Pull requests 2 Projects Releases Packages Wiki Activity

docs(media): reusable diagrams, logos, screenshots, and product blurbs #15

New issue
Open
opened 2026-09-13 17:45:50 +00:00 by PlasticDigits · 0 comments
PlasticDigits commented 2026-09-13 17:45:50 +00:00
Owner
Copy link

Summary

https://docs.cl8y.com has no first-party media kit: no downloadable ecosystem or flow diagrams, no approved logo files, no same-origin product screenshots, and no short technically reviewed blurbs that a post, video, or community explanation can reuse without scraping a long-form page.

Ship one prerendered media-kit page plus same-origin static files so a human can, with JavaScript off:

  1. Download an ecosystem diagram (CL8Y, Bridge, DEX, CMM) as a real SVG (and a raster companion).
  2. Download at least one flow diagram (inbound Bridge → DEX first use, and the reverse outbound path) as a real SVG (and a raster companion).
  3. Download approved CL8Y marks (wordmark / icon) already used on first-party surfaces — not a newly invented trademark.
  4. Download useful product screenshots of first-party UIs (empty/unconnected chrome only) when a honest capture exists; omit a slot rather than invent chrome.
  5. Copy short product and mechanics blurbs that match the claim rules on this host (same facts as Start Here / facts; not a second whitepaper).

The files must be designed for reuse in posts, videos, and community explanations: stable same-origin URLs, versioned filenames, labeled SVG text, and blurbs short enough to paste. They must not exist only as inline markup inside / or a how-to.

Bundle (do not split into logos / diagrams / screenshots / blurbs tickets). Do not put this kit on / (Start Here, code/cl8y-docs#9), /facts (code/cl8y-docs#14), or the how-to / FAQ paths owned by #10–#13.

v0 platform work (#3) already shipped crawl files, unique titles, and stub routes. Full manuscripts and a media kit were out of scope there.

Parent / siblings (do not re-implement)

  • code/cl8y-docs#3 — v0 host + stubs; out of scope: “Full methodology/guide manuscripts (stubs only).”
  • code/cl8y-docs#9 — Start Here on / (newcomer product map + one inline connection diagram + token purposes). Cite and link. That ticket must not register /media or a downloadable kit. If #9 lands an inline SVG, this issue’s ecosystem file is the shareable source; / may embed the same file later, but #9 stays a manuscript on /.
  • code/cl8y-docs#10 / #11 / #12 — how-to manuscripts. Optional screenshots there stay inside those guides. Different reader job: teach a flow vs hand a reusable file.
  • code/cl8y-docs#13 — token/treasury FAQ. Mechanics depth stays there; this page only ships short reviewed blurbs plus a pointer.
  • code/cl8y-docs#14 — verified facts and status. Canonical claim ledger; this kit must not contradict it. Do not duplicate the seven-section ledger here.
  • docs/ARCHITECTURE.md §4 / §5 / §7 / §12 / INVARIANTS 13–14, 19 — closed route allowlist; no unverified stats; no unpublished marketing content/guides/; og:image only if a real file; hashed-asset nginx regex today treats all .svg/.png as 7-day immutable.
  • src/components/Layout.tsx — text wordmark “CL8Y docs” only. No logo file in public/ today (robots.txt + generated sitemap.xml only).
  • code/CL8Y-web — marketing homepage (cl8y.com). Different deployable. Source of existing marks/favicons if already first-party; do not copy that SPA.
  • PlasticDigits/cl8y-marketing — governance parent (#3). Do not grow an app or dump unpublished content/guides/ here (INVARIANT 14 / 20).

Current codebase

There is no media surface:

  • src/seo.ts — closed DocsPath union of seven v0 paths. No /media.
  • src/lib/dexHref.ts — CAMPAIGNS closed vocabulary; no media.
  • src/App.tsx — seven Route entries; unknown paths 404 via nginx try_files $uri $uri/index.html =404.
  • src/pages/HomePage.tsx — host-chrome stub (Start Here manuscript is #9, not this kit).
  • src/pages/GuidesPage.tsx — forbids dumping unpublished marketing manuscripts; lists only /guides/open-the-dex.
  • src/content/invariants.ts — BANNED_CURRENT_COPY / FORBIDDEN_CLAIM_PATTERNS.
  • public/ — no PNG/SVG/ICO. Optional og:image is omitted on purpose (ARCHITECTURE §5).
  • nginx/default.conf — location ~* \.(js|css|png|jpg|jpeg|gif|svg|ico|woff2?)$ sets Cache-Control: public, max-age=604800, immutable and missing files 404 via @hashed_asset_miss. Vite hashed bundles belong there; unversioned kit files must not pretend to be content-hashed.
  • e2e/crawl.spec.ts + src/verify-dist.test.ts — unique titles/canonicals and sitemap locs follow the seven (until sibling PRs add rows). e2e/crawl.spec.ts currently hardcodes the v0 list.

Architecture §4 has no media-kit row. A complete kit therefore must add one allowlisted HTML path in the same PR (seo union, campaign id, App route, prerender, sitemap, crawl tests, ARCHITECTURE §4) plus real files under a versioned /media/ prefix.

Duplicates / already implemented

Work Action
#1 architecture, #2 review, #5 CI Unrelated; do not reopen
#3 v0 stubs Prerequisite host; not this kit
#9 Start Here Inline diagram + product map on /; not a downloadable kit
#10–#12 how-tos, #13 FAQ Different reader jobs; screenshots there are not the kit
#14 Facts and status Claim ledger; link it; do not merge
CL8Y-web homepage / token directory Different repo. Marks may be sourced, not vendored as that SPA
Unpublished marketing content/guides/ Forbidden to dump here (INVARIANTS 14)

If /media already exists with unique title/canonical, the five kit sections in prerendered HTML, versioned same-origin diagram/logo files that curl as image/svg+xml or image/png (not HTML), and AC1–AC12 pass, close as implemented — do not duplicate.

Why the new implementation is needed

Operators and community members currently have no first-party URL whose job is reuse. #9 will explain products on /. How-tos will teach steps. #14 will list what is live. None of those are a pack of files you can drop into a video or a post without cropping a documentation page.

Without this kit:

  • Diagrams exist only (or will exist only) inside long-form HTML and cannot be linked as stable SVG/PNG URLs.
  • Logos are whatever someone screenshots from a live SPA, including chrome that is not an approved mark.
  • Product one-liners drift across chats because there is no short, tested blurb module.

This is documentation copy + same-origin static files + one new prerendered route. No new host, no wallet UI, no Coolify SKU pick.

Constraints / guardrails

  1. Route. One new HTML path: /media. Canonical https://docs.cl8y.com/media (no trailing slash). Title seed: Media kit · CL8Y docs (wordsmith OK; must stay unique vs existing and sibling routes). Do not add /brand, /press, /assets (Vite hashed bundles), /status, or /ust1.
  2. Allowlist amendment (same PR). Update docs/ARCHITECTURE.md §4, docs/INVARIANTS.md campaign list, src/seo.ts DocsPath/ROUTES, src/lib/dexHref.ts CAMPAIGNS, src/App.tsx, src/components/Layout.tsx nav, e2e/crawl.spec.ts (prefer deriving from ROUTES so loc count is not hardcoded 7/8/9), and src/lib/dexHref.test.ts closed-campaign snapshot. scripts/prerender.mjs already follows ROUTES — do not hardcode a second loc list. Sitemap HTML loc is /media only — do not add every PNG/SVG as sitemap loc.
  3. Reader. Marketer, video editor, or community member who needs a file or a two-sentence description. Not a trading tutorial, not Start Here, not the facts ledger.
  4. Downloadable files (required). Real files in public/media/ (copied into dist/media/). Versioned names, for example cl8y-ecosystem-v1.svg, cl8y-flow-bridge-dex-v1.svg, cl8y-mark-v1.svg. GET of each file returns the image bytes, not index.html. Content-Type must be image/svg+xml or image/png (or image/jpeg if a screenshot is JPEG). Missing file → 404, not a media-page HTML 200.
  5. Nginx / cache. Today every .svg/.png is immutable for 7 days. Kit files are not Vite hashes. In the same PR either:
    • ship versioned filenames and never reuse a name for a different drawing, and add an explicit location ^~ /media/ that serves those files with nosniff + clickjacking headers, try_files $uri =404, and without immutable (short max-age or no-store is OK), or
    • keep the hashed regex only for /assets/ (Vite) and stop treating /media/* as hashed.
      Do not weaken hashed-miss 404 for JS/CSS. Do not introduce SPA fallback.
  6. Diagrams. First-party SVG with visible text labels (not outlines-only). Accessible: title/desc or adjacent HTML list on /media. No three.js, no mermaid runtime, no remote image CDN, no hotlinked DEX/Bridge origin. Arrows must not include TVL, volume, fee %, APY, or SLA minutes. Ecosystem diagram names CL8Y, Bridge, DEX, CMM. Flow diagram is a high-level Bridge ↔ DEX path (inbound then outbound), not a substitute for #10–#12.
  7. Logos. Only marks already used on first-party surfaces (this host’s wordmark, and/or marks already shipped on cl8y.com / DEX / Bridge public chrome). If no vector mark exists, ship an SVG wordmark that matches this host’s “CL8Y” text treatment — do not invent a mascot, GameFi character, or third-party logo. Do not include partner/CEX/CoinGecko marks.
  8. Screenshots. Optional per product but the slot is required on the page: DEX, Bridge, and this docs host. Rules:
    • Same-origin files only.
    • Unconnected UI: no seed, QR, WalletConnect modal, account address, balances, or P&L.
    • No third-party terminal, Telegram, or operator consoles.
    • If a honest capture cannot be taken without forbidden chrome, the slot says so in one sentence and ships no file (fail closed).
  9. Blurbs. Put strings in src/content/media.ts (or equivalent) and unit-test them. Required subjects: CL8Y (utility token for DEX fee tiers — no invented tier table), Bridge, DEX, CMM (names only for CMM tokens; same bounded USTR/UST1 exception as #9, only on /media and this module, not leaked onto methodology stubs). Each blurb: one or two sentences. Point at /, /facts (if #14 has landed or is linked as forthcoming), /contracts, and the live first-party origins. Do not copy unpublished marketing manuscripts. If #9/#14 content modules exist, reuse those strings rather than forking facts.
  10. Claims. No fee, TVL, volume, ranking, collateral ratio, circulating supply, or APY figures unless already printed as first-party constants in this repo (they are not). No CoinGecko/CMC/DeFiLlama. BANNED_CURRENT_COPY stays except the bounded CMM name exception above. No “Buy CL8Y” CTA. Do not list GameFi / PROTOCASS / Karnyx / TigerHunt.
  11. Links. Build with URL (not string concat, not window.location, not visitor query). Download hrefs are same-origin /media/… paths. Official product links: docs /, DEX via dexHref { campaign: "media" }, Bridge https://bridge.cl8y.com, homepage https://cl8y.com. rel="noopener noreferrer" if target="_blank". No javascript:, data:, protocol-relative, or ?url= redirectors.
  12. CTAs. New campaign id media (closed vocabulary). DEX CTA still dexHref with execute ids, not tickers. The primary job of this page is download/copy, not “Open the DEX” as the only heading.
  13. Nav / hubs. Add Media (or Media kit) to Layout nav and one link from / and /guides (one line each). Do not duplicate Start Here or how-to manuscripts on /media.
  14. No wallet / trading UI. No wagmi, WalletConnect, LCD keys, iframes of DEX/Bridge, or screenshots that are live embeds.
  15. Do not publish ops internals, unpublished marketing manuscripts, extra contract addresses, or operator/host/Coolify copy.

Relevant files

Path Why
src/pages/MediaPage.tsx (new) Kit index: blurbs + download list
src/content/media.ts (new) Blurbs, file inventory, unit tests
public/media/* (new) Versioned SVG/PNG (and optional screenshots)
src/seo.ts New path/title/description/campaign
src/App.tsx Register /media
src/components/Layout.tsx Nav item
src/lib/dexHref.ts Campaign media
src/lib/dexHref.test.ts Closed campaign snapshot
src/pages/HomePage.tsx / GuidesPage.tsx One link to /media
nginx/default.conf /media/ location vs hashed-asset regex
e2e/crawl.spec.ts Unique title/canonical; file Content-Type sniff
src/verify-dist.test.ts Follows ROUTES; body sniff for kit headings; files exist and are not HTML
docs/ARCHITECTURE.md §4 / §5 / §7 / §12 New route; kit files; cache rule
docs/INVARIANTS.md Campaign + route; still no unverified claims
scripts/prerender.mjs No loc hardcode; sitemap gains /media HTML only

Recommended direction

  1. Content module first: src/content/media.ts with blurb strings, files: { id, href, mime, version }[]. Unit-test: forbidden claim patterns, banned copy (with the CMM name allowlist scoped to this module), every href starts with /media/ and a version suffix, no foreign hosts.
  2. Draw SVGs as source files in public/media/ (plain SVG, text labels, no embedded bitmap unless a screenshot slot). Keep ecosystem geometry compatible with #9 so / and the kit cannot disagree.
  3. MediaPage: H1 Media kit; sections Diagrams, Logos, Screenshots, Product blurbs; each file is an <a href> to the versioned path. Optional img preview with alt matching the blurb.
  4. Register the route through seo.ts so prerender + sitemap cannot drift. Campaign media.
  5. nginx: explicit /media/ location before the hashed regex (prefix ^~). Confirm GET /media still serves media/index.html (HTML) while GET /media/cl8y-ecosystem-v1.svg serves SVG.
  6. Do not change Dockerfile, Woodpecker shape, or MIME rules for robots/sitemap. Unknown paths still 404.

Acceptance criteria

  • AC1. GET /media prerendered HTML (no JS) contains headings (or equivalent labeled sections) for diagrams, logos, screenshots, and product blurbs.
  • AC2. The same HTML contains first-party blurbs for CL8Y, Bridge, DEX, and CMM, with no invented statistics and no GameFi lore.
  • AC3. GET /media/cl8y-ecosystem-v1.svg (exact versioned name OK if documented in the module) returns 200 image/svg+xml (or SVG sniffed, not <!doctype html>). Flow diagram file likewise.
  • AC4. At least one approved mark file is a real same-origin SVG or PNG; the page links it. No third-party venue logos.
  • AC5. Screenshot slots for DEX, Bridge, and docs are present. Each either serves a same-origin image of unconnected chrome or an explicit “no capture” sentence. No wallet/seed/address/P&L pixels.
  • AC6. /media unique title (Media kit · CL8Y docs or equivalent); canonical https://docs.cl8y.com/media. Sitemap loc set is previous prerendered HTML paths plus this one. Kit binaries are not sitemap locs. Unknown paths still 404. GET /media/no-such.svg is 404, not the kit HTML.
  • AC7. Layout nav and / (and /guides) link to /media.
  • AC8. DEX CTA on this page uses dexHref default pair + utm_campaign=media. Download hrefs are same-origin /media/… only.
  • AC9. No TVL / “best DEX” / CoinGecko / CMC / DeFiLlama / fabricated fee tiers. “Buy CL8Y” is not a CTA. UST1 / USTR appear only as factual CMM names in this kit (or tests fail closed if they leak onto other stubs).
  • AC10. npm test, npm run typecheck, npm run build + dist unique-title tests, Playwright 5 workers stay green.
  • AC11. robots/sitemap MIME, clickjacking headers, and missing hashed JS/CSS 404 behavior unchanged.
  • AC12. Architecture §4 and the CAMPAIGNS snapshot document /media / media. Nginx /media/ vs hashed assets is documented in §7.

Given a marketer or community member opens the prerendered /media page When they read the media kit without executing JavaScript Then they can download same-origin ecosystem and flow diagrams, an approved mark, and (when present) unconnected product screenshots, and they can copy short technically reviewed product blurbs, with no invented statistics and no files that exist only inside another manuscript

Test plan (functional paths)

# Path Expect
T1 dist/media/index.html Unique title/canonical; four kit sections present
T2 Same file, no JS Blurbs name CL8Y, Bridge, DEX, CMM; no TVL / “best DEX”
T3 GET /media/<ecosystem-file>.svg 200; body starts with <svg (or XML svg); not doctype html
T4 GET /media/<flow-file>.svg Same as T3
T5 Logo file 200 image; linked from prerendered HTML
T6 Screenshot slots Image 200 or explicit omitted sentence; never WC/seed chrome
T7 sitemap.xml Contains https://docs.cl8y.com/media; still no DEX loc; no .svg locs required
T8 /, /guides, Layout nav Link to /media
T9 GET /no-such-page and GET /media/missing.svg 404
T10 Unit: media.ts Forbidden claim patterns fail if someone pastes TVL / “best DEX”; hrefs are /media/ + version
T11 Playwright 5 workers New HTML route in crawl table; previous routes still pass
T12 GET /media Content-Type HTML; kit SVG/PNG are not labeled text/html

Test plan (copy and file safety)

Not a DeFi attack suite. Keep host crawl/CTA tests from #3 green.

# Vector Expect
C1 Unverified TVL/volume/fee % on /media or in SVG text Fail AC9 / unit grep
C2 GameFi / PROTOCASS / Karnyx / TigerHunt Absent
C3 Primary CTA “Buy CL8Y” or third-party venue as official Forbidden
C4 javascript: / data: / protocol-relative download or product href Never emitted
C5 Visitor query concatenated onto Bridge/DEX/homepage Forbidden
C6 Sitemap loc to a foreign host or to javascript: Forbidden
C7 Dump of unpublished marketing guides Forbidden
C8 USTR/UST1 on /methodology stub via shared layout Fail; exception is /media (and #9 /) copy only
C9 Invented contract not in contracts.ts Fail review
C10 Wallet/WC/trading UI or iframe of DEX/Bridge Fail review
C11 Missing SVG served as kit HTML 200 Fail AC3 / T9
C12 Unversioned kit file advertised as immutable forever Fail AC12 / nginx rule
C13 Remote CDN / hotlink to dex.cl8y.com or bridge.cl8y.com as the file body Forbidden; same-origin only
C14 Operator/host/Coolify/uptime status copy Forbidden on this public page
C15 New mascot / unofficial “approved” mark not used on a first-party surface Forbidden

Verification criteria

  • npm test && npm run typecheck && production npm run build with required VITE_*.
  • npm run test:dist (unique titles/canonicals including /media).
  • Playwright 5 workers: /media body sniff for the four sections + at least one SVG href; crawl MIME tests unchanged; binary GETs sniff SVG/PNG vs HTML.
  • Human: open prerendered /media and confirm a marketer can download diagrams/marks and paste blurbs without opening a how-to.
  • scripts/check-origins.mjs still fail-closed without HTTPS origins.
  • No Coolify hostname/SKU work in this PR.

Out of scope

  • Operator incident/uptime status, Coolify, hosts, VMs, tokens, or queue ids.
  • Wallet connect, swap execution, wrap/mint UI, pair create.
  • Publishing unpublished marketing manuscripts from PlasticDigits/cl8y-marketing.
  • Inventing DEX fee-tier tables, CMM collateral ratios, extra addresses, or a product roadmap.
  • Expanding the USTR/UST1 name exception onto methodology/markets stubs.
  • Editing code/CL8Y-web, code/ustr-cmm, the Bridge monorepo, or the DEX SPA (read-only for names, origins, and existing marks).
  • Implementing #9/#10–#14 manuscripts in this PR (link and reuse strings if those modules already exist).
  • DEX Sitemap: pointer (marketing#2).
  • Choosing hypervisor image, SKU, or a new host.

First-pass model recommendation

Recommendation: grok-high

Rationale: This is a new public route plus a first-party brand/media pack, not docs/test-only maintenance of an existing stub. It amends the closed architecture allowlist, sitemap loc set, dexHref campaign vocabulary, and nginx static-file caching (unhashed /media/ vs Vite hashed assets). Expected files span MediaPage / media content module, versioned SVG/PNG under public/media/, seo.ts, App.tsx, Layout.tsx, dexHref + tests, nginx, crawl/dist assertions, and ARCHITECTURE.md / INVARIANTS.md — more than three production files and a cross-cutting prerender/cache contract. Composer fails those criteria (local three-file edit, no allowlist/protocol change, no brand-claim risk). Risk is claim-safety and cache-poisoning a “canonical” diagram or mark. Verify with unique-title/canonical dist tests, Playwright 5 workers, copy greps, and curl of SVG/PNG vs HTML. Control-plane calibration: unlike a single RCA document (PR #170) or a test-helper tweak (#164), this is closer to a cross-module change (new route + nginx + crawl contract) than a one-file copy edit.

## Summary `https://docs.cl8y.com` has no first-party **media kit**: no downloadable ecosystem or flow diagrams, no approved logo files, no same-origin product screenshots, and no short technically reviewed blurbs that a post, video, or community explanation can reuse without scraping a long-form page. Ship one prerendered media-kit page plus same-origin static files so a human can, with JavaScript off: 1. Download an ecosystem diagram (CL8Y, Bridge, DEX, CMM) as a real SVG (and a raster companion). 2. Download at least one flow diagram (inbound Bridge → DEX first use, and the reverse outbound path) as a real SVG (and a raster companion). 3. Download approved CL8Y marks (wordmark / icon) already used on first-party surfaces — not a newly invented trademark. 4. Download useful product screenshots of first-party UIs (empty/unconnected chrome only) when a honest capture exists; omit a slot rather than invent chrome. 5. Copy short product and mechanics blurbs that match the claim rules on this host (same facts as Start Here / facts; not a second whitepaper). The files must be designed for reuse in posts, videos, and community explanations: stable same-origin URLs, versioned filenames, labeled SVG text, and blurbs short enough to paste. They must not exist only as inline markup inside `/` or a how-to. Bundle (do not split into logos / diagrams / screenshots / blurbs tickets). Do not put this kit on `/` (Start Here, `code/cl8y-docs`#9), `/facts` (`code/cl8y-docs`#14), or the how-to / FAQ paths owned by #10–#13. v0 platform work (#3) already shipped crawl files, unique titles, and stub routes. Full manuscripts and a media kit were out of scope there. ### Parent / siblings (do not re-implement) - `code/cl8y-docs`#3 — v0 host + stubs; out of scope: “Full methodology/guide manuscripts (stubs only).” - `code/cl8y-docs`#9 — Start Here on `/` (newcomer product map + **one inline** connection diagram + token purposes). Cite and link. That ticket must **not** register `/media` or a downloadable kit. If #9 lands an inline SVG, this issue’s ecosystem file is the shareable source; `/` may embed the same file later, but #9 stays a manuscript on `/`. - `code/cl8y-docs`#10 / #11 / #12 — how-to manuscripts. Optional screenshots there stay inside those guides. Different reader job: teach a flow vs hand a reusable file. - `code/cl8y-docs`#13 — token/treasury FAQ. Mechanics depth stays there; this page only ships **short** reviewed blurbs plus a pointer. - `code/cl8y-docs`#14 — verified facts and status. Canonical claim ledger; this kit must not contradict it. Do not duplicate the seven-section ledger here. - `docs/ARCHITECTURE.md` §4 / §5 / §7 / §12 / INVARIANTS 13–14, 19 — closed route allowlist; no unverified stats; no unpublished marketing `content/guides/`; `og:image` only if a real file; hashed-asset nginx regex today treats **all** `.svg`/`.png` as 7-day `immutable`. - `src/components/Layout.tsx` — text wordmark “CL8Y docs” only. No logo file in `public/` today (`robots.txt` + generated `sitemap.xml` only). - `code/CL8Y-web` — marketing homepage (`cl8y.com`). Different deployable. Source of existing marks/favicons if already first-party; do not copy that SPA. - `PlasticDigits/cl8y-marketing` — governance parent (`#3`). Do not grow an app or dump unpublished `content/guides/` here (INVARIANT 14 / 20). ## Current codebase There is no media surface: - `src/seo.ts` — closed `DocsPath` union of seven v0 paths. No `/media`. - `src/lib/dexHref.ts` — `CAMPAIGNS` closed vocabulary; no `media`. - `src/App.tsx` — seven `Route` entries; unknown paths 404 via nginx `try_files $uri $uri/index.html =404`. - `src/pages/HomePage.tsx` — host-chrome stub (Start Here manuscript is #9, not this kit). - `src/pages/GuidesPage.tsx` — forbids dumping unpublished marketing manuscripts; lists only `/guides/open-the-dex`. - `src/content/invariants.ts` — `BANNED_CURRENT_COPY` / `FORBIDDEN_CLAIM_PATTERNS`. - `public/` — no PNG/SVG/ICO. Optional `og:image` is omitted on purpose (ARCHITECTURE §5). - `nginx/default.conf` — `location ~* \.(js|css|png|jpg|jpeg|gif|svg|ico|woff2?)$` sets `Cache-Control: public, max-age=604800, immutable` and missing files 404 via `@hashed_asset_miss`. Vite hashed bundles belong there; **unversioned kit files must not pretend to be content-hashed**. - `e2e/crawl.spec.ts` + `src/verify-dist.test.ts` — unique titles/canonicals and sitemap locs follow the seven (until sibling PRs add rows). `e2e/crawl.spec.ts` currently hardcodes the v0 list. Architecture §4 has no media-kit row. A complete kit therefore must add **one** allowlisted HTML path in the same PR (seo union, campaign id, App route, prerender, sitemap, crawl tests, ARCHITECTURE §4) plus real files under a versioned `/media/` prefix. ### Duplicates / already implemented | Work | Action | | --- | --- | | #1 architecture, #2 review, #5 CI | Unrelated; do not reopen | | #3 v0 stubs | Prerequisite host; not this kit | | #9 Start Here | Inline diagram + product map on `/`; not a downloadable kit | | #10–#12 how-tos, #13 FAQ | Different reader jobs; screenshots there are not the kit | | #14 Facts and status | Claim ledger; link it; do not merge | | CL8Y-web homepage / token directory | Different repo. Marks may be **sourced**, not vendored as that SPA | | Unpublished marketing `content/guides/` | Forbidden to dump here (INVARIANTS 14) | If `/media` already exists with unique title/canonical, the five kit sections in prerendered HTML, versioned same-origin diagram/logo files that `curl` as image/svg+xml or image/png (not HTML), and AC1–AC12 pass, close as implemented — do not duplicate. ## Why the new implementation is needed Operators and community members currently have no first-party URL whose job is **reuse**. `#9` will explain products on `/`. How-tos will teach steps. `#14` will list what is live. None of those are a pack of files you can drop into a video or a post without cropping a documentation page. Without this kit: - Diagrams exist only (or will exist only) inside long-form HTML and cannot be linked as stable SVG/PNG URLs. - Logos are whatever someone screenshots from a live SPA, including chrome that is not an approved mark. - Product one-liners drift across chats because there is no short, tested blurb module. This is documentation copy + same-origin static files + one new prerendered route. No new host, no wallet UI, no Coolify SKU pick. ## Constraints / guardrails 1. **Route.** One new HTML path: `/media`. Canonical `https://docs.cl8y.com/media` (no trailing slash). Title seed: `Media kit · CL8Y docs` (wordsmith OK; must stay unique vs existing and sibling routes). Do not add `/brand`, `/press`, `/assets` (Vite hashed bundles), `/status`, or `/ust1`. 2. **Allowlist amendment (same PR).** Update `docs/ARCHITECTURE.md` §4, `docs/INVARIANTS.md` campaign list, `src/seo.ts` `DocsPath`/`ROUTES`, `src/lib/dexHref.ts` `CAMPAIGNS`, `src/App.tsx`, `src/components/Layout.tsx` nav, `e2e/crawl.spec.ts` (prefer deriving from `ROUTES` so loc count is not hardcoded 7/8/9), and `src/lib/dexHref.test.ts` closed-campaign snapshot. `scripts/prerender.mjs` already follows `ROUTES` — do not hardcode a second loc list. Sitemap **HTML loc** is `/media` only — do **not** add every PNG/SVG as sitemap `loc`. 3. **Reader.** Marketer, video editor, or community member who needs a file or a two-sentence description. Not a trading tutorial, not Start Here, not the facts ledger. 4. **Downloadable files (required).** Real files in `public/media/` (copied into `dist/media/`). Versioned names, for example `cl8y-ecosystem-v1.svg`, `cl8y-flow-bridge-dex-v1.svg`, `cl8y-mark-v1.svg`. `GET` of each file returns the image bytes, **not** `index.html`. Content-Type must be `image/svg+xml` or `image/png` (or `image/jpeg` if a screenshot is JPEG). Missing file → 404, not a media-page HTML 200. 5. **Nginx / cache.** Today every `.svg`/`.png` is `immutable` for 7 days. Kit files are **not** Vite hashes. In the same PR either: - ship **versioned** filenames and never reuse a name for a different drawing, **and** add an explicit `location ^~ /media/` that serves those files with `nosniff` + clickjacking headers, `try_files $uri =404`, and **without** `immutable` (short `max-age` or `no-store` is OK), **or** - keep the hashed regex only for `/assets/` (Vite) and stop treating `/media/*` as hashed. Do not weaken hashed-miss 404 for JS/CSS. Do not introduce SPA fallback. 6. **Diagrams.** First-party SVG with visible text labels (not outlines-only). Accessible: `title`/`desc` or adjacent HTML list on `/media`. No three.js, no mermaid runtime, no remote image CDN, no hotlinked DEX/Bridge origin. Arrows must not include TVL, volume, fee %, APY, or SLA minutes. Ecosystem diagram names CL8Y, Bridge, DEX, CMM. Flow diagram is a **high-level** Bridge ↔ DEX path (inbound then outbound), not a substitute for #10–#12. 7. **Logos.** Only marks already used on first-party surfaces (this host’s wordmark, and/or marks already shipped on `cl8y.com` / DEX / Bridge public chrome). If no vector mark exists, ship an SVG wordmark that matches this host’s “CL8Y” text treatment — do **not** invent a mascot, GameFi character, or third-party logo. Do not include partner/CEX/CoinGecko marks. 8. **Screenshots.** Optional per product but the **slot is required** on the page: DEX, Bridge, and this docs host. Rules: - Same-origin files only. - Unconnected UI: no seed, QR, WalletConnect modal, account address, balances, or P&L. - No third-party terminal, Telegram, or operator consoles. - If a honest capture cannot be taken without forbidden chrome, the slot says so in one sentence and ships no file (fail closed). 9. **Blurbs.** Put strings in `src/content/media.ts` (or equivalent) and unit-test them. Required subjects: CL8Y (utility token for DEX fee tiers — no invented tier table), Bridge, DEX, CMM (names only for CMM tokens; same bounded USTR/UST1 exception as #9, **only** on `/media` and this module, not leaked onto methodology stubs). Each blurb: one or two sentences. Point at `/`, `/facts` (if #14 has landed or is linked as forthcoming), `/contracts`, and the live first-party origins. Do not copy unpublished marketing manuscripts. If #9/#14 content modules exist, **reuse** those strings rather than forking facts. 10. **Claims.** No fee, TVL, volume, ranking, collateral ratio, circulating supply, or APY figures unless already printed as first-party constants in this repo (they are not). No CoinGecko/CMC/DeFiLlama. `BANNED_CURRENT_COPY` stays except the bounded CMM name exception above. No “Buy CL8Y” CTA. Do not list GameFi / PROTOCASS / Karnyx / TigerHunt. 11. **Links.** Build with `URL` (not string concat, not `window.location`, not visitor query). Download `href`s are same-origin `/media/…` paths. Official product links: docs `/`, DEX via `dexHref` `{ campaign: "media" }`, Bridge `https://bridge.cl8y.com`, homepage `https://cl8y.com`. `rel="noopener noreferrer"` if `target="_blank"`. No `javascript:`, `data:`, protocol-relative, or `?url=` redirectors. 12. **CTAs.** New campaign id `media` (closed vocabulary). DEX CTA still `dexHref` with execute ids, not tickers. The primary job of this page is download/copy, not “Open the DEX” as the only heading. 13. **Nav / hubs.** Add Media (or Media kit) to `Layout` nav and one link from `/` and `/guides` (one line each). Do not duplicate Start Here or how-to manuscripts on `/media`. 14. **No wallet / trading UI.** No wagmi, WalletConnect, LCD keys, iframes of DEX/Bridge, or screenshots that are live embeds. 15. **Do not** publish ops internals, unpublished marketing manuscripts, extra contract addresses, or operator/host/Coolify copy. ## Relevant files | Path | Why | | --- | --- | | `src/pages/MediaPage.tsx` (new) | Kit index: blurbs + download list | | `src/content/media.ts` (new) | Blurbs, file inventory, unit tests | | `public/media/*` (new) | Versioned SVG/PNG (and optional screenshots) | | `src/seo.ts` | New path/title/description/campaign | | `src/App.tsx` | Register `/media` | | `src/components/Layout.tsx` | Nav item | | `src/lib/dexHref.ts` | Campaign `media` | | `src/lib/dexHref.test.ts` | Closed campaign snapshot | | `src/pages/HomePage.tsx` / `GuidesPage.tsx` | One link to `/media` | | `nginx/default.conf` | `/media/` location vs hashed-asset regex | | `e2e/crawl.spec.ts` | Unique title/canonical; file Content-Type sniff | | `src/verify-dist.test.ts` | Follows `ROUTES`; body sniff for kit headings; files exist and are not HTML | | `docs/ARCHITECTURE.md` §4 / §5 / §7 / §12 | New route; kit files; cache rule | | `docs/INVARIANTS.md` | Campaign + route; still no unverified claims | | `scripts/prerender.mjs` | No loc hardcode; sitemap gains `/media` HTML only | ## Recommended direction 1. Content module first: `src/content/media.ts` with blurb strings, `files: { id, href, mime, version }[]`. Unit-test: forbidden claim patterns, banned copy (with the CMM name allowlist scoped to this module), every `href` starts with `/media/` and a version suffix, no foreign hosts. 2. Draw SVGs as source files in `public/media/` (plain SVG, text labels, no embedded bitmap unless a screenshot slot). Keep ecosystem geometry compatible with #9 so `/` and the kit cannot disagree. 3. `MediaPage`: H1 Media kit; sections Diagrams, Logos, Screenshots, Product blurbs; each file is an `<a href>` to the versioned path. Optional `img` preview with `alt` matching the blurb. 4. Register the route through `seo.ts` so prerender + sitemap cannot drift. Campaign `media`. 5. nginx: explicit `/media/` location **before** the hashed regex (prefix `^~`). Confirm `GET /media` still serves `media/index.html` (HTML) while `GET /media/cl8y-ecosystem-v1.svg` serves SVG. 6. Do not change Dockerfile, Woodpecker shape, or MIME rules for robots/sitemap. Unknown paths still 404. ## Acceptance criteria - AC1. `GET /media` prerendered HTML (no JS) contains headings (or equivalent labeled sections) for diagrams, logos, screenshots, and product blurbs. - AC2. The same HTML contains first-party blurbs for CL8Y, Bridge, DEX, and CMM, with no invented statistics and no GameFi lore. - AC3. `GET /media/cl8y-ecosystem-v1.svg` (exact versioned name OK if documented in the module) returns 200 `image/svg+xml` (or SVG sniffed, not `<!doctype html>`). Flow diagram file likewise. - AC4. At least one approved mark file is a real same-origin SVG or PNG; the page links it. No third-party venue logos. - AC5. Screenshot slots for DEX, Bridge, and docs are present. Each either serves a same-origin image of unconnected chrome or an explicit “no capture” sentence. No wallet/seed/address/P&L pixels. - AC6. `/media` unique title (`Media kit · CL8Y docs` or equivalent); canonical `https://docs.cl8y.com/media`. Sitemap loc set is previous prerendered HTML paths plus this one. Kit binaries are **not** sitemap locs. Unknown paths still 404. `GET /media/no-such.svg` is 404, not the kit HTML. - AC7. Layout nav and `/` (and `/guides`) link to `/media`. - AC8. DEX CTA on this page uses `dexHref` default pair + `utm_campaign=media`. Download hrefs are same-origin `/media/…` only. - AC9. No TVL / “best DEX” / CoinGecko / CMC / DeFiLlama / fabricated fee tiers. “Buy CL8Y” is not a CTA. `UST1` / `USTR` appear only as factual CMM names in this kit (or tests fail closed if they leak onto other stubs). - AC10. `npm test`, `npm run typecheck`, `npm run build` + dist unique-title tests, Playwright 5 workers stay green. - AC11. robots/sitemap MIME, clickjacking headers, and missing hashed JS/CSS 404 behavior unchanged. - AC12. Architecture §4 and the `CAMPAIGNS` snapshot document `/media` / `media`. Nginx `/media/` vs hashed assets is documented in §7. Given a marketer or community member opens the prerendered `/media` page When they read the media kit without executing JavaScript Then they can download same-origin ecosystem and flow diagrams, an approved mark, and (when present) unconnected product screenshots, and they can copy short technically reviewed product blurbs, with no invented statistics and no files that exist only inside another manuscript ## Test plan (functional paths) | # | Path | Expect | | --- | --- | --- | | T1 | `dist/media/index.html` | Unique title/canonical; four kit sections present | | T2 | Same file, no JS | Blurbs name CL8Y, Bridge, DEX, CMM; no TVL / “best DEX” | | T3 | `GET /media/<ecosystem-file>.svg` | 200; body starts with `<svg` (or XML svg); not doctype html | | T4 | `GET /media/<flow-file>.svg` | Same as T3 | | T5 | Logo file | 200 image; linked from prerendered HTML | | T6 | Screenshot slots | Image 200 **or** explicit omitted sentence; never WC/seed chrome | | T7 | `sitemap.xml` | Contains `https://docs.cl8y.com/media`; still no DEX loc; no `.svg` locs required | | T8 | `/`, `/guides`, Layout nav | Link to `/media` | | T9 | `GET /no-such-page` and `GET /media/missing.svg` | 404 | | T10 | Unit: `media.ts` | Forbidden claim patterns fail if someone pastes TVL / “best DEX”; hrefs are `/media/` + version | | T11 | Playwright 5 workers | New HTML route in crawl table; previous routes still pass | | T12 | `GET /media` Content-Type | HTML; kit SVG/PNG are not labeled `text/html` | ## Test plan (copy and file safety) Not a DeFi attack suite. Keep host crawl/CTA tests from #3 green. | # | Vector | Expect | | --- | --- | --- | | C1 | Unverified TVL/volume/fee % on `/media` or in SVG text | Fail AC9 / unit grep | | C2 | GameFi / PROTOCASS / Karnyx / TigerHunt | Absent | | C3 | Primary CTA “Buy CL8Y” or third-party venue as official | Forbidden | | C4 | `javascript:` / `data:` / protocol-relative download or product href | Never emitted | | C5 | Visitor query concatenated onto Bridge/DEX/homepage | Forbidden | | C6 | Sitemap loc to a foreign host or to `javascript:` | Forbidden | | C7 | Dump of unpublished marketing guides | Forbidden | | C8 | USTR/UST1 on `/methodology` stub via shared layout | Fail; exception is `/media` (and #9 `/`) copy only | | C9 | Invented contract not in `contracts.ts` | Fail review | | C10 | Wallet/WC/trading UI or iframe of DEX/Bridge | Fail review | | C11 | Missing SVG served as kit HTML 200 | Fail AC3 / T9 | | C12 | Unversioned kit file advertised as `immutable` forever | Fail AC12 / nginx rule | | C13 | Remote CDN / hotlink to dex.cl8y.com or bridge.cl8y.com as the file body | Forbidden; same-origin only | | C14 | Operator/host/Coolify/uptime status copy | Forbidden on this public page | | C15 | New mascot / unofficial “approved” mark not used on a first-party surface | Forbidden | ## Verification criteria - `npm test` && `npm run typecheck` && production `npm run build` with required `VITE_*`. - `npm run test:dist` (unique titles/canonicals including `/media`). - Playwright 5 workers: `/media` body sniff for the four sections + at least one SVG `href`; crawl MIME tests unchanged; binary `GET`s sniff SVG/PNG vs HTML. - Human: open prerendered `/media` and confirm a marketer can download diagrams/marks and paste blurbs without opening a how-to. - `scripts/check-origins.mjs` still fail-closed without HTTPS origins. - No Coolify hostname/SKU work in this PR. ## Out of scope - Operator incident/uptime status, Coolify, hosts, VMs, tokens, or queue ids. - Wallet connect, swap execution, wrap/mint UI, pair create. - Publishing unpublished marketing manuscripts from `PlasticDigits/cl8y-marketing`. - Inventing DEX fee-tier tables, CMM collateral ratios, extra addresses, or a product roadmap. - Expanding the USTR/UST1 name exception onto methodology/markets stubs. - Editing `code/CL8Y-web`, `code/ustr-cmm`, the Bridge monorepo, or the DEX SPA (read-only for names, origins, and existing marks). - Implementing #9/#10–#14 manuscripts in this PR (link and reuse strings if those modules already exist). - DEX `Sitemap:` pointer (marketing#2). - Choosing hypervisor image, SKU, or a new host. ## First-pass model recommendation Recommendation: grok-high Rationale: This is a new public route plus a first-party brand/media pack, not docs/test-only maintenance of an existing stub. It amends the closed architecture allowlist, sitemap loc set, `dexHref` campaign vocabulary, and nginx static-file caching (unhashed `/media/` vs Vite hashed assets). Expected files span `MediaPage` / `media` content module, versioned SVG/PNG under `public/media/`, `seo.ts`, `App.tsx`, `Layout.tsx`, `dexHref` + tests, nginx, crawl/dist assertions, and `ARCHITECTURE.md` / `INVARIANTS.md` — more than three production files and a cross-cutting prerender/cache contract. Composer fails those criteria (local three-file edit, no allowlist/protocol change, no brand-claim risk). Risk is claim-safety and cache-poisoning a “canonical” diagram or mark. Verify with unique-title/canonical dist tests, Playwright 5 workers, copy greps, and `curl` of SVG/PNG vs HTML. Control-plane calibration: unlike a single RCA document (PR #170) or a test-helper tweak (#164), this is closer to a cross-module change (new route + nginx + crawl contract) than a one-file copy edit.
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
main
renovate/configure
No results found.
Labels
Clear labels   
agent:implement
Agent implement gate

  
agent:research
Research gate; skip implement admit

  
docs

   
feature
Product feature; do not apply ready until gates pass

  
ready
Ready for agent pickup

  
research
Design/architecture; not implement

No labels
agent:implement
agent:research
docs
feature
ready
research
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
code/cl8y-docs#15
No description provided.