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

docs(guides): practical Bridge how-to #11

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

Summary

https://docs.cl8y.com/guides currently lists only the Open the DEX CTA stub. There is no crawlable first-party page that explains how to use the CL8Y Bridge: which chains and assets are supported, how to move funds in both directions, what gas is required on each side, which costs are Bridge charges versus network fees or taxes imposed elsewhere, how long a transfer typically takes, and what to do when a transfer fails or stalls.

Ship one prerendered practical Bridge guide on a new allowlisted path so a reader can complete a round-trip using the live first-party Bridge without treating docs as a wallet, operator console, or fee oracle.

Bundle (do not split into chains / fees / taxes / recovery tickets):

  1. Supported chains, assets, and routes as already published on the Bridge UI or in code/cl8y-bridge-monorepo public docs.
  2. Numbered inbound and outbound steps (source chain → dest chain and the reverse), pointing at https://bridge.cl8y.com.
  3. Required native gas tokens per side (name the kinds; do not invent a CEX list).
  4. Cost kinds: CL8Y Bridge fee versus destination/source network gas versus any tax imposed by the underlying chain — with a clear sentence that this page does not freeze percentages, USD, or SLA minutes unless that exact figure already exists as a first-party constant.
  5. Typical completion: point at the live Transfer Status / remaining-time chrome on the Bridge; do not invent a guaranteed duration.
  6. Common errors and user-facing recovery (wrong address format, missing dest gas, below-min / rate-limit, stalled status after a source tx).

Keep /guides/open-the-dex as the CTA-only child. Do not put this manuscript on / (Start Here, code/cl8y-docs#9) or on /guides/first-use (code/cl8y-docs#10).

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

Parent / siblings (do not re-implement):

  • code/cl8y-docs#3 — v0 host + stubs; /guides/open-the-dex purpose remains “follow the first-party CTA. Not a trading tutorial.”
  • code/cl8y-docs#9 — Start Here on / (product map). Bridge is one or two sentences there, not a how-to. Cite and link; do not expand that ticket.
  • code/cl8y-docs#10 — first-use walkthrough (wallet → gas → inbound → first DEX swap → outbound). That ticket must not add /guides/bridge. This issue owns the dedicated Bridge how-to. Do not merge manuscripts; do not rewrite #10’s first-swap path here.
  • docs/ARCHITECTURE.md §4 / §12 — closed route allowlist; no unverified stats; no unpublished marketing content/guides/.
  • code/cl8y-bridge-monorepo — source of currently published supported chains/assets, Bridge fee presentation, Transfer Status remaining-time chrome, and user-visible error copy. Read, do not vendor unpublished operator internals.
  • code/CL8Y-web#1 — CL8Y utility-token wording. Different deployable.

Current codebase

Guides index has no Bridge child:

  • src/pages/GuidesPage.tsx — lists only /guides/open-the-dex. Copy forbids dumping unpublished marketing manuscripts.
  • src/pages/OpenDexPage.tsx — DEX CTA stub; not a Bridge tutorial.
  • src/seo.ts — closed DocsPath union of seven v0 paths. No /guides/bridge.
  • src/lib/dexHref.ts — CAMPAIGNS closed vocabulary; no guides-bridge.
  • src/lib/ — no bridgeHref helper yet (#9/#10 may add one; reuse if present, otherwise add here with tests).
  • src/App.tsx — seven Route entries; unknown paths 404 via nginx try_files … =404.
  • src/content/invariants.ts — BANNED_CURRENT_COPY / FORBIDDEN_CLAIM_PATTERNS (no TVL / “best DEX” / CoinGecko / CMC / DeFiLlama; no “Buy CL8Y” CTA).
  • e2e/crawl.spec.ts — hardcodes the seven v0 paths (must follow ROUTES after this path is added; do not assume loc count 7 or 8 if #10 lands first).
  • src/verify-dist.test.ts — follows ROUTES; sitemap loc count follows that module.
  • Architecture §4: no Bridge how-to row.

A complete Bridge manuscript therefore must add one allowlisted path in the same PR (seo union, campaign id, App route, prerender, sitemap, crawl tests, ARCHITECTURE §4). Do not overload /guides/open-the-dex. Do not overload /guides/first-use (#10). Do not add /guides/wallet or /guides/withdraw.

Duplicates / already implemented

Work Action
#1 architecture, #2 review, #5 CI Unrelated; do not reopen
#3 v0 stubs Prerequisite host; Open the DEX stays CTA-only
#9 Start Here on / Sibling map; different problem (what exists vs how to bridge)
#10 first-use walkthrough Sibling how-to; includes inbound/outbound as two phases of a first DEX trade. Different primary reader job. That PR must not register /guides/bridge.
Unpublished marketing content/guides/ Forbidden to dump here (INVARIANTS 14)
Bridge SPA at https://bridge.cl8y.com Cite the live UI; do not copy the Bridge app into this host
Bridge-monorepo operator / security tickets Different repo; do not file recovery as ops runbooks on this host

If /guides/bridge already exists as a complete prerendered how-to (published routes both directions, gas kinds, Bridge fee vs network fee/tax, completion via live UI, common errors + recovery) and AC1–AC12 pass, close as implemented — do not duplicate.

Why the new implementation is needed

The public docs origin is the URL operators hand people who ask how to move funds. Today:

  • /guides never names the Bridge as a how-to.
  • #9 maps the product in one or two sentences; it does not teach a transfer.
  • #10 teaches a first DEX use and must not grow a second guides child in that PR.
  • Fee, tax, duration, and recovery questions get answered in chat with no crawlable first-party page, which invites invented percentages and SLA claims.

This is documentation copy + one new prerendered route + optional same-origin screenshots. No wallet SDK, no deposit/withdraw execution on this host, no Coolify SKU pick.

Constraints / guardrails

  1. Route. Add exactly one path: /guides/bridge. Title seed Bridge · Guides · CL8Y docs (wordsmith OK; must stay unique vs existing routes and vs #10’s first-use title if that page exists). Canonical https://docs.cl8y.com/guides/bridge (no trailing slash). Amend ARCHITECTURE §4 in the same PR. Do not add /guides/wallet or /guides/withdraw.
  2. Reader. Someone who already knows they want to move a supported asset between supported chains. Numbered steps. Short sentences. One scrollable manuscript with in-page headings: Supported routes, Inbound, Outbound, Gas, Costs (Bridge vs network / tax), Completion time, Common errors and recovery. Not a whitepaper. Not Start Here (#9). Not a first DEX trade (#10).
  3. This host stays static. INVARIANTS 19: no wagmi, WalletConnect, three.js, LCD keys, or Bridge/DEX screens running here. Describe using whatever wallets the live Bridge already documents. Do not mint a wallet directory. Do not ask the reader to connect a wallet on docs.cl8y.com.
  4. Routes and assets. Supported chains/assets = the set already published on the Bridge UI or code/cl8y-bridge-monorepo public docs. If a route is not published first-party, omit it (“see Bridge”) — do not reconstruct from chat or memory. Do not list GameFi / PROTOCASS / Karnyx / TigerHunt. Do not invent contract strings beyond src/data/contracts.ts unless copied from that file.
  5. Both directions. Cover source→dest and dest→source as user steps on the first-party Bridge. Do not claim every listed asset is bidirectional unless the published Bridge UI shows both directions. If a direction is unpublished, say to check the live picker.
  6. Gas. Name native gas kinds per published chain family (for example Terra Classic native LUNC / uluna distinct from CW20 wrap legs; EVM native gas; Solana native SOL) only where the Bridge UI already requires them. Do not invent a CEX list or “Buy CL8Y” as the gas path. Never present a third-party venue as the primary CTA.
  7. Costs: Bridge vs elsewhere. Required distinction:
    • CL8Y Bridge charge — whatever fee the live Bridge UI already shows for the transfer (protocol / mapping fee). Point at that chrome. Do not freeze a percentage, bps, or USD.
    • Network fees — source and destination gas paid to the chain, not to CL8Y.
    • Taxes imposed elsewhere — only if a published first-party Bridge or chain surface already names a tax (for example a Terra Classic on-chain tax). Name the kind. Do not invent a rate, and do not attribute a chain tax to the CL8Y Bridge.
      Pattern: “the live Bridge UI shows the current Bridge fee and remaining time; this page does not freeze a number.” No CoinGecko/CMC/DeFiLlama. No fabricated fee tables.
  8. Completion time. Do not print a guaranteed minute/hour SLA. Point at the Bridge Transfer Status remaining-time UI (code/cl8y-bridge-monorepo published chrome). Allowed: qualitative “not instant; wait for dest confirmation shown in Transfer Status.” Forbidden: invented “usually N minutes.”
  9. Errors and recovery (user-facing only). Cover at least:
    • Wrong chain or wrong address format (Terra bech32 vs EVM 0x vs Solana).
    • Missing native gas on source (cannot send) or dest (cannot complete withdraw / submit).
    • Amount below published minimum or blocked by a published rate limit — wait / reduce; do not tell users to bypass limits.
    • Stalled Transfer Status after a source transaction — refresh on the Bridge origin; do not double-submit a dest step unless the live UI says the previous dest tx failed; keep the transfer hash.
      Do not publish operator recovery, RPC lists, Coolify, queue ids, canceler/operator runbooks, or contract admin steps.
  10. Screenshots (optional but in-scope). Same-origin files only (public/guides/bridge/ or equivalent). First-party Bridge chrome, cropped, no seed phrases, no live balances presented as current, no third-party CEX UI. Alt text that remains true if images fail. No remote image CDN, no mermaid runtime. If screenshots would go stale faster than copy, ship the prose first.
  11. Claims / copy bans. Keep BANNED_CURRENT_COPY and FORBIDDEN_CLAIM_PATTERNS. No GameFi lore. “Buy CL8Y” is not a CTA. Do not dump unpublished marketing manuscripts. USTR/UST1: not required on this page (that exception is #9’s CMM section on / only).
  12. CTAs. Bridge via tested helper/constant: new URL("/", "https://bridge.cl8y.com") (path / or a documented first-party Bridge path only). rel="noopener noreferrer" if target="_blank". Layout may keep dexHref with new campaign guides-bridge (extend CAMPAIGNS) so crawl tests that sniff DEX CTAs stay honest. Do not concatenate visitor query. No javascript: / data: / protocol-relative / ?url= redirectors. Tickers must never appear as execute ids.
  13. Guides index. /guides lists Bridge beside Open the DEX (and First use if #10 has shipped). One-line each; do not duplicate the manuscript on the index.
  14. Home. Optional one-line link from / once #9’s Start Here exists; not required to block this PR. Do not redefine / in this issue.
  15. Sitemap / nginx. Loc count follows ROUTES (seven v0 + this path, plus /guides/first-use only if #10 already merged). nginx try_files unchanged. Unknown paths still 404. Do not change Dockerfile, Woodpecker shape, or DEX Sitemap: pointer.
  16. Do not publish ops internals, queue ids, host/SKU, or extra contract strings beyond src/data/contracts.ts.

Relevant files

Path Why
src/pages/BridgeGuidePage.tsx (new) How-to manuscript
src/content/bridgeGuide.ts (new, preferred) Strings + section ids so unit tests can forbid hype / unverified fee, tax, and SLA figures without rendering React
src/pages/GuidesPage.tsx Index link to /guides/bridge
src/App.tsx Register the route
src/seo.ts New DocsPath, title, description, campaign
src/lib/dexHref.ts + dexHref.test.ts Add guides-bridge to CAMPAIGNS (Layout CTA)
src/lib/bridgeHref.ts (new unless #9/#10 already added it) new URL("/", "https://bridge.cl8y.com") + unit tests
src/data/contracts.ts Reuse published strings only; do not invent
src/content/invariants.ts Unchanged bans; Bridge copy must still fail closed
e2e/crawl.spec.ts New path: unique title/canonical; body sniff for required headings. Prefer deriving the path table from ROUTES so #10 cannot desync loc count.
src/verify-dist.test.ts Follows ROUTES; sitemap loc includes the new path only on this origin
docs/ARCHITECTURE.md §4 / §10 / §12 Allowlist row; campaign id; claims still apply to how-to copy
docs/INVARIANTS.md Campaign list; still no unverified fee/tax/SLA figures; still no wallet UI
skills/docs-static-host/SKILL.md / docs-dex-cta New path + campaign
public/guides/bridge/ Optional screenshots
code/cl8y-bridge-monorepo Read published routes, fee chrome, Transfer Status, user-visible errors only
code/cl8y-docs#9 and #10 Sibling manuscripts; do not merge

Recommended direction

  1. Extract copy into src/content/bridgeGuide.ts (section titles + body strings + cost-kind sentences with no numeric literals unless sourced). Unit-test: banned hype, no javascript:, no ticker execute ids, no unverified % / TVL / “usually N minutes” / invented tax rates.
  2. BridgeGuidePage: H1 Bridge; ordered sections; Bridge CTA through URL helper; DEX header CTA through dexHref + guides-bridge.
  3. Extend DocsPath / CAMPAIGNS / App / prerender. Sitemap is generated from seo.ts — do not hand-edit a second allowlist that can drift. Update e2e/crawl.spec.ts from ROUTES rather than a hardcoded seven-row table if that is still duplicated.
  4. GuidesPage: stub line “Bridge — supported routes, both directions, gas, Bridge fee vs network fees or taxes, completion, recovery.”
  5. Playwright: prerendered HTML (no JS) contains the required headings; crawl MIME tests unchanged; 404 still 404.
  6. Do not change nginx, Dockerfile, or add WalletConnect.

Acceptance criteria

  • AC1. GET /guides/bridge prerendered HTML (no JS) contains a Bridge heading and sections for supported routes, inbound, outbound, gas, costs, completion time, and common errors/recovery.
  • AC2. The same HTML names fee/tax kinds (CL8Y Bridge charge vs network gas vs tax imposed elsewhere) and points at the live Bridge UI; it contains no invented percentages, USD, TVL, volume, ranking, or guaranteed minute/hour SLA.
  • AC3. The same HTML states that a chain tax or network fee is not a CL8Y Bridge charge, using only kinds that are already published first-party. If no first-party tax is published, say network fees are paid to the chain and omit an invented tax row.
  • AC4. Recovery copy covers at least: wrong address format, missing native gas, below-min or rate-limit, stalled Transfer Status — without operator/RPC/host internals.
  • AC5. Bridge href is https://bridge.cl8y.com (path / or a documented first-party path only). rel safe if new tab. No visitor-query concat.
  • AC6. Unique title (Bridge · Guides · CL8Y docs or equivalent); canonical https://docs.cl8y.com/guides/bridge. Other v0 routes keep their titles (home may change only via #9; first-use only via #10).
  • AC7. /guides links to /guides/bridge. /guides/open-the-dex still exists and still is not rewritten into this manuscript. /guides/first-use is neither created nor rewritten by this PR.
  • AC8. Sitemap loc includes the new path on https://docs.cl8y.com only. Unknown paths 404. robots/sitemap MIME unchanged.
  • AC9. No wagmi / WalletConnect / seed-phrase UI. No “Buy CL8Y” CTA. No GameFi lore. No unpublished marketing dump.
  • AC10. Screenshots, if any, are same-origin, alt-texted, and do not show seeds or claimed-live balances. If omitted, AC1–AC9 still pass.
  • AC11. npm test, npm run typecheck, production npm run build with required VITE_*, npm run test:dist, Playwright 5 workers stay green.
  • AC12. ARCHITECTURE §4 lists /guides/bridge. CAMPAIGNS includes guides-bridge.

Given a reader opens the prerendered /guides/bridge page
When they read the how-to without executing JavaScript
Then they can identify published supported routes, follow inbound and outbound steps on the first-party Bridge, name required gas kinds, distinguish CL8Y Bridge charges from network fees or taxes imposed elsewhere, understand that completion time comes from live Transfer Status rather than a frozen SLA, and apply user-facing recovery for common errors — without invented statistics or a wallet UI on this host

Test plan (functional paths)

# Path Expect
T1 dist/guides/bridge/index.html Unique title/canonical; Bridge H1
T2 Same file, no JS Headings for routes, inbound, outbound, gas, costs, completion, recovery
T3 Same file Cost-kind copy present; no % fee/tax table unless sourced constant; no “usually N minutes”
T4 Bridge anchor https://bridge.cl8y.com; rel safe if new tab
T5 Layout DEX CTA dexHref + utm_campaign=guides-bridge
T6 /guides HTML Link to /guides/bridge
T7 /guides/open-the-dex Still CTA-only; not replaced
T8 GET /guides/wallet (unlisted) 404
T9 Unit: bridgeGuide.ts Forbidden claim patterns fail if someone pastes TVL / “best DEX” / fee % / invented tax rate / SLA minutes
T10 Playwright 5 workers New path in crawl table; previous routes still pass

Test plan (copy safety)

Not a DeFi attack suite. Keep host crawl/CTA tests from #3 green. Do not add abuse/hack tests.

# Vector Expect
C1 Unverified TVL/volume/fee % / tax rate / SLA minutes on the new page Fail AC2 / unit grep
C2 GameFi / PROTOCASS / Karnyx / TigerHunt Absent
C3 Primary CTA “Buy CL8Y” or third-party venue Forbidden
C4 javascript: / data: / protocol-relative Bridge href Never emitted
C5 Visitor query concatenated onto Bridge/DEX Forbidden
C6 Sitemap loc to a foreign host Forbidden
C7 Dump of unpublished marketing guides Forbidden
C8 WalletConnect / wagmi / seed screenshot Fail review
C9 Invented contract not in contracts.ts Fail review
C10 Teaching users to connect a wallet on docs.cl8y.com Forbidden (connect on Bridge/DEX origins only)
C11 Attributing a chain tax to the CL8Y Bridge Fail AC3
C12 Operator recovery, RPC lists, host/SKU, canceler steps Out of scope; fail review
C13 Expanding #9’s / or #10’s first-use into this how-to Out of scope

Verification criteria

  • npm test && npm run typecheck && production npm run build with required VITE_*.
  • npm run test:dist (unique titles/canonicals including the new path).
  • Playwright 5 workers: Bridge body sniff for required headings; crawl MIME tests unchanged.
  • Human: open prerendered /guides/bridge and confirm a reader can answer “which routes / how both directions / what gas / what does the Bridge charge vs the chain / how long / what if it stalls?” from the page alone, without connecting a wallet on this host.
  • Existing scripts/check-origins.mjs still fail-closed without HTTPS origins.
  • No Coolify hostname/SKU work in this PR.

Out of scope

  • Redefining / (that is #9) or implementing /guides/first-use (that is #10).
  • Replacing /guides/open-the-dex or adding more than one new path.
  • Wallet connect, deposit/withdraw execution, wrap/mint UI on this host.
  • Publishing unpublished marketing manuscripts.
  • Inventing Bridge fee percentages, tax rates, completion SLAs, CMM collateral ratios, or extra addresses.
  • Editing code/CL8Y-web, code/cl8y-dex-terraclassic, or code/cl8y-bridge-monorepo except as read-only sources.
  • nginx, Dockerfile, Woodpecker shape, or DEX Sitemap: pointer.
  • Choosing hypervisor image, SKU, or a new host.
  • Operator incident recovery.

First-pass model recommendation

Recommendation: grok-high

Rationale: This is a newcomer-facing Bridge how-to that must source published chains/assets, distinguish protocol fees from network gas and any chain tax, and describe completion/recovery without freezing SLA or rate numbers. Composer’s docs/test-only path does not apply: product claims (routes, fee kinds, tax attribution, remaining-time chrome) must be read from code/cl8y-bridge-monorepo / the live Bridge UI, the change expands the closed allowlist (DocsPath, CAMPAIGNS, prerender, sitemap, ARCHITECTURE §4), and the expected files exceed a single-subsystem three-file edit (BridgeGuidePage, bridgeGuide copy module, seo/campaigns, App, guides index, bridgeHref helper, architecture/invariants, crawl tests). Uncertain published-route/fee/tax/time presentation fails the “known local edit” bar. Comparable control-plane calibration: a single RCA Markdown would be Composer; this is closer to a cross-module content-policy change than a test-helper tweak.

## Summary `https://docs.cl8y.com/guides` currently lists only the Open the DEX CTA stub. There is no crawlable first-party page that explains how to use the CL8Y Bridge: which chains and assets are supported, how to move funds in both directions, what gas is required on each side, which costs are Bridge charges versus network fees or taxes imposed elsewhere, how long a transfer typically takes, and what to do when a transfer fails or stalls. Ship **one** prerendered practical Bridge guide on a **new** allowlisted path so a reader can complete a round-trip using the live first-party Bridge without treating docs as a wallet, operator console, or fee oracle. Bundle (do not split into chains / fees / taxes / recovery tickets): 1. Supported chains, assets, and routes as **already published** on the Bridge UI or in `code/cl8y-bridge-monorepo` public docs. 2. Numbered inbound and outbound steps (source chain → dest chain and the reverse), pointing at `https://bridge.cl8y.com`. 3. Required native gas tokens per side (name the **kinds**; do not invent a CEX list). 4. Cost kinds: CL8Y Bridge fee versus destination/source network gas versus any tax imposed by the underlying chain — with a clear sentence that this page does not freeze percentages, USD, or SLA minutes unless that exact figure already exists as a first-party constant. 5. Typical completion: point at the live Transfer Status / remaining-time chrome on the Bridge; do not invent a guaranteed duration. 6. Common errors and user-facing recovery (wrong address format, missing dest gas, below-min / rate-limit, stalled status after a source tx). Keep `/guides/open-the-dex` as the CTA-only child. Do not put this manuscript on `/` (Start Here, `code/cl8y-docs`#9) or on `/guides/first-use` (`code/cl8y-docs`#10). v0 platform work (#3) already shipped crawl files, unique titles, and stub routes. Full Bridge manuscripts were out of scope there. Parent / siblings (do not re-implement): - `code/cl8y-docs`#3 — v0 host + stubs; `/guides/open-the-dex` purpose remains “follow the first-party CTA. Not a trading tutorial.” - `code/cl8y-docs`#9 — Start Here on `/` (product map). Bridge is one or two sentences there, not a how-to. Cite and link; do not expand that ticket. - `code/cl8y-docs`#10 — first-use walkthrough (wallet → gas → inbound → first DEX swap → outbound). That ticket **must not** add `/guides/bridge`. This issue owns the dedicated Bridge how-to. Do not merge manuscripts; do not rewrite #10’s first-swap path here. - `docs/ARCHITECTURE.md` §4 / §12 — closed route allowlist; no unverified stats; no unpublished marketing `content/guides/`. - `code/cl8y-bridge-monorepo` — source of **currently published** supported chains/assets, Bridge fee presentation, Transfer Status remaining-time chrome, and user-visible error copy. Read, do not vendor unpublished operator internals. - `code/CL8Y-web`#1 — CL8Y utility-token wording. Different deployable. ## Current codebase Guides index has no Bridge child: - `src/pages/GuidesPage.tsx` — lists only `/guides/open-the-dex`. Copy forbids dumping unpublished marketing manuscripts. - `src/pages/OpenDexPage.tsx` — DEX CTA stub; not a Bridge tutorial. - `src/seo.ts` — closed `DocsPath` union of seven v0 paths. No `/guides/bridge`. - `src/lib/dexHref.ts` — `CAMPAIGNS` closed vocabulary; no `guides-bridge`. - `src/lib/` — no `bridgeHref` helper yet (#9/#10 may add one; reuse if present, otherwise add here with tests). - `src/App.tsx` — seven `Route` entries; unknown paths 404 via nginx `try_files … =404`. - `src/content/invariants.ts` — `BANNED_CURRENT_COPY` / `FORBIDDEN_CLAIM_PATTERNS` (no TVL / “best DEX” / CoinGecko / CMC / DeFiLlama; no “Buy CL8Y” CTA). - `e2e/crawl.spec.ts` — hardcodes the seven v0 paths (must follow `ROUTES` after this path is added; do not assume loc count 7 or 8 if #10 lands first). - `src/verify-dist.test.ts` — follows `ROUTES`; sitemap loc count follows that module. - Architecture §4: no Bridge how-to row. A complete Bridge manuscript therefore **must add one allowlisted path** in the same PR (seo union, campaign id, App route, prerender, sitemap, crawl tests, ARCHITECTURE §4). Do not overload `/guides/open-the-dex`. Do not overload `/guides/first-use` (#10). Do not add `/guides/wallet` or `/guides/withdraw`. ### Duplicates / already implemented | Work | Action | | --- | --- | | #1 architecture, #2 review, #5 CI | Unrelated; do not reopen | | #3 v0 stubs | Prerequisite host; Open the DEX stays CTA-only | | #9 Start Here on `/` | Sibling map; different problem (what exists vs how to bridge) | | #10 first-use walkthrough | Sibling how-to; includes inbound/outbound as two phases of a first DEX trade. Different primary reader job. That PR must not register `/guides/bridge`. | | Unpublished marketing `content/guides/` | Forbidden to dump here (INVARIANTS 14) | | Bridge SPA at `https://bridge.cl8y.com` | Cite the live UI; do not copy the Bridge app into this host | | Bridge-monorepo operator / security tickets | Different repo; do not file recovery as ops runbooks on this host | If `/guides/bridge` already exists as a complete prerendered how-to (published routes both directions, gas kinds, Bridge fee vs network fee/tax, completion via live UI, common errors + recovery) and AC1–AC12 pass, close as implemented — do not duplicate. ## Why the new implementation is needed The public docs origin is the URL operators hand people who ask how to move funds. Today: - `/guides` never names the Bridge as a how-to. - #9 maps the product in one or two sentences; it does not teach a transfer. - #10 teaches a first DEX use and must not grow a second guides child in that PR. - Fee, tax, duration, and recovery questions get answered in chat with no crawlable first-party page, which invites invented percentages and SLA claims. This is documentation copy + one new prerendered route + optional same-origin screenshots. No wallet SDK, no deposit/withdraw execution on this host, no Coolify SKU pick. ## Constraints / guardrails 1. **Route.** Add exactly one path: `/guides/bridge`. Title seed `Bridge · Guides · CL8Y docs` (wordsmith OK; must stay unique vs existing routes and vs #10’s first-use title if that page exists). Canonical `https://docs.cl8y.com/guides/bridge` (no trailing slash). Amend ARCHITECTURE §4 in the same PR. Do not add `/guides/wallet` or `/guides/withdraw`. 2. **Reader.** Someone who already knows they want to move a supported asset between supported chains. Numbered steps. Short sentences. One scrollable manuscript with in-page headings: Supported routes, Inbound, Outbound, Gas, Costs (Bridge vs network / tax), Completion time, Common errors and recovery. Not a whitepaper. Not Start Here (#9). Not a first DEX trade (#10). 3. **This host stays static.** INVARIANTS 19: no wagmi, WalletConnect, three.js, LCD keys, or Bridge/DEX screens **running here**. Describe using whatever wallets the live Bridge already documents. Do not mint a wallet directory. Do not ask the reader to connect a wallet on `docs.cl8y.com`. 4. **Routes and assets.** Supported chains/assets = the set **already published** on the Bridge UI or `code/cl8y-bridge-monorepo` public docs. If a route is not published first-party, omit it (“see Bridge”) — do not reconstruct from chat or memory. Do not list GameFi / PROTOCASS / Karnyx / TigerHunt. Do not invent contract strings beyond `src/data/contracts.ts` unless copied from that file. 5. **Both directions.** Cover source→dest and dest→source as user steps on the first-party Bridge. Do not claim every listed asset is bidirectional unless the published Bridge UI shows both directions. If a direction is unpublished, say to check the live picker. 6. **Gas.** Name native gas **kinds** per published chain family (for example Terra Classic native LUNC / `uluna` distinct from CW20 wrap legs; EVM native gas; Solana native SOL) only where the Bridge UI already requires them. Do not invent a CEX list or “Buy CL8Y” as the gas path. Never present a third-party venue as the primary CTA. 7. **Costs: Bridge vs elsewhere.** Required distinction: - **CL8Y Bridge charge** — whatever fee the live Bridge UI already shows for the transfer (protocol / mapping fee). Point at that chrome. Do not freeze a percentage, bps, or USD. - **Network fees** — source and destination gas paid to the chain, not to CL8Y. - **Taxes imposed elsewhere** — only if a published first-party Bridge or chain surface already names a tax (for example a Terra Classic on-chain tax). Name the **kind**. Do not invent a rate, and do not attribute a chain tax to the CL8Y Bridge. Pattern: “the live Bridge UI shows the current Bridge fee and remaining time; this page does not freeze a number.” No CoinGecko/CMC/DeFiLlama. No fabricated fee tables. 8. **Completion time.** Do not print a guaranteed minute/hour SLA. Point at the Bridge Transfer Status remaining-time UI (`code/cl8y-bridge-monorepo` published chrome). Allowed: qualitative “not instant; wait for dest confirmation shown in Transfer Status.” Forbidden: invented “usually N minutes.” 9. **Errors and recovery (user-facing only).** Cover at least: - Wrong chain or wrong address format (Terra bech32 vs EVM `0x` vs Solana). - Missing native gas on source (cannot send) or dest (cannot complete withdraw / submit). - Amount below published minimum or blocked by a published rate limit — wait / reduce; do not tell users to bypass limits. - Stalled Transfer Status after a source transaction — refresh on the Bridge origin; do not double-submit a dest step unless the live UI says the previous dest tx failed; keep the transfer hash. Do **not** publish operator recovery, RPC lists, Coolify, queue ids, canceler/operator runbooks, or contract admin steps. 10. **Screenshots (optional but in-scope).** Same-origin files only (`public/guides/bridge/` or equivalent). First-party Bridge chrome, cropped, no seed phrases, no live balances presented as current, no third-party CEX UI. Alt text that remains true if images fail. No remote image CDN, no mermaid runtime. If screenshots would go stale faster than copy, ship the prose first. 11. **Claims / copy bans.** Keep `BANNED_CURRENT_COPY` and `FORBIDDEN_CLAIM_PATTERNS`. No GameFi lore. “Buy CL8Y” is not a CTA. Do not dump unpublished marketing manuscripts. USTR/UST1: not required on this page (that exception is #9’s CMM section on `/` only). 12. **CTAs.** Bridge via tested helper/constant: `new URL("/", "https://bridge.cl8y.com")` (path `/` or a documented first-party Bridge path only). `rel="noopener noreferrer"` if `target="_blank"`. Layout may keep `dexHref` with new campaign `guides-bridge` (extend `CAMPAIGNS`) so crawl tests that sniff DEX CTAs stay honest. Do not concatenate visitor query. No `javascript:` / `data:` / protocol-relative / `?url=` redirectors. Tickers must never appear as execute ids. 13. **Guides index.** `/guides` lists Bridge beside Open the DEX (and First use if #10 has shipped). One-line each; do not duplicate the manuscript on the index. 14. **Home.** Optional one-line link from `/` once #9’s Start Here exists; not required to block this PR. Do not redefine `/` in this issue. 15. **Sitemap / nginx.** Loc count follows `ROUTES` (seven v0 + this path, plus `/guides/first-use` only if #10 already merged). nginx `try_files` unchanged. Unknown paths still 404. Do not change Dockerfile, Woodpecker shape, or DEX `Sitemap:` pointer. 16. **Do not** publish ops internals, queue ids, host/SKU, or extra contract strings beyond `src/data/contracts.ts`. ## Relevant files | Path | Why | | --- | --- | | `src/pages/BridgeGuidePage.tsx` (new) | How-to manuscript | | `src/content/bridgeGuide.ts` (new, preferred) | Strings + section ids so unit tests can forbid hype / unverified fee, tax, and SLA figures without rendering React | | `src/pages/GuidesPage.tsx` | Index link to `/guides/bridge` | | `src/App.tsx` | Register the route | | `src/seo.ts` | New `DocsPath`, title, description, campaign | | `src/lib/dexHref.ts` + `dexHref.test.ts` | Add `guides-bridge` to `CAMPAIGNS` (Layout CTA) | | `src/lib/bridgeHref.ts` (new unless #9/#10 already added it) | `new URL("/", "https://bridge.cl8y.com")` + unit tests | | `src/data/contracts.ts` | Reuse published strings only; do not invent | | `src/content/invariants.ts` | Unchanged bans; Bridge copy must still fail closed | | `e2e/crawl.spec.ts` | New path: unique title/canonical; body sniff for required headings. Prefer deriving the path table from `ROUTES` so #10 cannot desync loc count. | | `src/verify-dist.test.ts` | Follows `ROUTES`; sitemap loc includes the new path only on this origin | | `docs/ARCHITECTURE.md` §4 / §10 / §12 | Allowlist row; campaign id; claims still apply to how-to copy | | `docs/INVARIANTS.md` | Campaign list; still no unverified fee/tax/SLA figures; still no wallet UI | | `skills/docs-static-host/SKILL.md` / `docs-dex-cta` | New path + campaign | | `public/guides/bridge/` | Optional screenshots | | `code/cl8y-bridge-monorepo` | Read published routes, fee chrome, Transfer Status, user-visible errors only | | `code/cl8y-docs`#9 and #10 | Sibling manuscripts; do not merge | ## Recommended direction 1. Extract copy into `src/content/bridgeGuide.ts` (section titles + body strings + cost-kind sentences with no numeric literals unless sourced). Unit-test: banned hype, no `javascript:`, no ticker execute ids, no unverified `%` / TVL / “usually N minutes” / invented tax rates. 2. `BridgeGuidePage`: H1 Bridge; ordered sections; Bridge CTA through URL helper; DEX header CTA through `dexHref` + `guides-bridge`. 3. Extend `DocsPath` / `CAMPAIGNS` / `App` / prerender. Sitemap is generated from `seo.ts` — do not hand-edit a second allowlist that can drift. Update `e2e/crawl.spec.ts` from `ROUTES` rather than a hardcoded seven-row table if that is still duplicated. 4. `GuidesPage`: stub line “Bridge — supported routes, both directions, gas, Bridge fee vs network fees or taxes, completion, recovery.” 5. Playwright: prerendered HTML (no JS) contains the required headings; crawl MIME tests unchanged; 404 still 404. 6. Do not change nginx, Dockerfile, or add WalletConnect. ## Acceptance criteria - AC1. `GET /guides/bridge` prerendered HTML (no JS) contains a Bridge heading and sections for supported routes, inbound, outbound, gas, costs, completion time, and common errors/recovery. - AC2. The same HTML names fee/tax **kinds** (CL8Y Bridge charge vs network gas vs tax imposed elsewhere) and points at the live Bridge UI; it contains **no** invented percentages, USD, TVL, volume, ranking, or guaranteed minute/hour SLA. - AC3. The same HTML states that a chain tax or network fee is not a CL8Y Bridge charge, using only kinds that are already published first-party. If no first-party tax is published, say network fees are paid to the chain and omit an invented tax row. - AC4. Recovery copy covers at least: wrong address format, missing native gas, below-min or rate-limit, stalled Transfer Status — without operator/RPC/host internals. - AC5. Bridge href is `https://bridge.cl8y.com` (path `/` or a documented first-party path only). `rel` safe if new tab. No visitor-query concat. - AC6. Unique title (`Bridge · Guides · CL8Y docs` or equivalent); canonical `https://docs.cl8y.com/guides/bridge`. Other v0 routes keep their titles (home may change only via #9; first-use only via #10). - AC7. `/guides` links to `/guides/bridge`. `/guides/open-the-dex` still exists and still is not rewritten into this manuscript. `/guides/first-use` is neither created nor rewritten by this PR. - AC8. Sitemap loc includes the new path on `https://docs.cl8y.com` only. Unknown paths 404. robots/sitemap MIME unchanged. - AC9. No wagmi / WalletConnect / seed-phrase UI. No “Buy CL8Y” CTA. No GameFi lore. No unpublished marketing dump. - AC10. Screenshots, if any, are same-origin, alt-texted, and do not show seeds or claimed-live balances. If omitted, AC1–AC9 still pass. - AC11. `npm test`, `npm run typecheck`, production `npm run build` with required `VITE_*`, `npm run test:dist`, Playwright 5 workers stay green. - AC12. ARCHITECTURE §4 lists `/guides/bridge`. `CAMPAIGNS` includes `guides-bridge`. Given a reader opens the prerendered `/guides/bridge` page When they read the how-to without executing JavaScript Then they can identify published supported routes, follow inbound and outbound steps on the first-party Bridge, name required gas kinds, distinguish CL8Y Bridge charges from network fees or taxes imposed elsewhere, understand that completion time comes from live Transfer Status rather than a frozen SLA, and apply user-facing recovery for common errors — without invented statistics or a wallet UI on this host ## Test plan (functional paths) | # | Path | Expect | | --- | --- | --- | | T1 | `dist/guides/bridge/index.html` | Unique title/canonical; Bridge H1 | | T2 | Same file, no JS | Headings for routes, inbound, outbound, gas, costs, completion, recovery | | T3 | Same file | Cost-kind copy present; no `%` fee/tax table unless sourced constant; no “usually N minutes” | | T4 | Bridge anchor | `https://bridge.cl8y.com`; `rel` safe if new tab | | T5 | Layout DEX CTA | `dexHref` + `utm_campaign=guides-bridge` | | T6 | `/guides` HTML | Link to `/guides/bridge` | | T7 | `/guides/open-the-dex` | Still CTA-only; not replaced | | T8 | `GET /guides/wallet` (unlisted) | 404 | | T9 | Unit: `bridgeGuide.ts` | Forbidden claim patterns fail if someone pastes TVL / “best DEX” / fee `%` / invented tax rate / SLA minutes | | T10 | Playwright 5 workers | New path in crawl table; previous routes still pass | ## Test plan (copy safety) Not a DeFi attack suite. Keep host crawl/CTA tests from #3 green. Do not add abuse/hack tests. | # | Vector | Expect | | --- | --- | --- | | C1 | Unverified TVL/volume/fee % / tax rate / SLA minutes on the new page | Fail AC2 / unit grep | | C2 | GameFi / PROTOCASS / Karnyx / TigerHunt | Absent | | C3 | Primary CTA “Buy CL8Y” or third-party venue | Forbidden | | C4 | `javascript:` / `data:` / protocol-relative Bridge href | Never emitted | | C5 | Visitor query concatenated onto Bridge/DEX | Forbidden | | C6 | Sitemap loc to a foreign host | Forbidden | | C7 | Dump of unpublished marketing guides | Forbidden | | C8 | WalletConnect / wagmi / seed screenshot | Fail review | | C9 | Invented contract not in `contracts.ts` | Fail review | | C10 | Teaching users to connect a wallet **on docs.cl8y.com** | Forbidden (connect on Bridge/DEX origins only) | | C11 | Attributing a chain tax to the CL8Y Bridge | Fail AC3 | | C12 | Operator recovery, RPC lists, host/SKU, canceler steps | Out of scope; fail review | | C13 | Expanding #9’s `/` or #10’s first-use into this how-to | Out of scope | ## Verification criteria - `npm test` && `npm run typecheck` && production `npm run build` with required `VITE_*`. - `npm run test:dist` (unique titles/canonicals including the new path). - Playwright 5 workers: Bridge body sniff for required headings; crawl MIME tests unchanged. - Human: open prerendered `/guides/bridge` and confirm a reader can answer “which routes / how both directions / what gas / what does the Bridge charge vs the chain / how long / what if it stalls?” from the page alone, without connecting a wallet on this host. - Existing `scripts/check-origins.mjs` still fail-closed without HTTPS origins. - No Coolify hostname/SKU work in this PR. ## Out of scope - Redefining `/` (that is #9) or implementing `/guides/first-use` (that is #10). - Replacing `/guides/open-the-dex` or adding more than one new path. - Wallet connect, deposit/withdraw execution, wrap/mint UI **on this host**. - Publishing unpublished marketing manuscripts. - Inventing Bridge fee percentages, tax rates, completion SLAs, CMM collateral ratios, or extra addresses. - Editing `code/CL8Y-web`, `code/cl8y-dex-terraclassic`, or `code/cl8y-bridge-monorepo` except as read-only sources. - nginx, Dockerfile, Woodpecker shape, or DEX `Sitemap:` pointer. - Choosing hypervisor image, SKU, or a new host. - Operator incident recovery. ## First-pass model recommendation Recommendation: grok-high Rationale: This is a newcomer-facing Bridge how-to that must source published chains/assets, distinguish protocol fees from network gas and any chain tax, and describe completion/recovery without freezing SLA or rate numbers. Composer’s docs/test-only path does not apply: product claims (routes, fee kinds, tax attribution, remaining-time chrome) must be read from `code/cl8y-bridge-monorepo` / the live Bridge UI, the change expands the closed allowlist (`DocsPath`, `CAMPAIGNS`, prerender, sitemap, ARCHITECTURE §4), and the expected files exceed a single-subsystem three-file edit (`BridgeGuidePage`, `bridgeGuide` copy module, seo/campaigns, App, guides index, bridgeHref helper, architecture/invariants, crawl tests). Uncertain published-route/fee/tax/time presentation fails the “known local edit” bar. Comparable control-plane calibration: a single RCA Markdown would be Composer; this is closer to a cross-module content-policy change than a test-helper tweak.
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#11
No description provided.