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

docs(guides): first-user walkthrough from wallet to trade #10

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

Summary

https://docs.cl8y.com/guides/open-the-dex is a first-party CTA stub: it tells the reader to open the DEX and explicitly is not a trading tutorial. A newcomer who has no wallet, no Terra Classic gas, and no assets on the right chain still cannot go from that page to a completed first use of CL8Y.

Ship one prerendered first-user walkthrough on a new allowlisted path so a reader with nothing set up can follow a single manuscript through:

  1. Wallet setup (compatible Terra Classic wallet; describe, do not embed a wallet UI on this host).
  2. Obtaining the required gas token (native LUNC / uluna).
  3. Bringing supported funds into the ecosystem via the first-party Bridge.
  4. Completing a first swap on the first-party DEX (default pair: uluna → Terra Classic CL8Y CW20).
  5. Moving funds back out via the Bridge.
  6. Supported routes, fee kinds, common mistakes, and optional first-party screenshots.

Bundle (do not split into wallet / gas / bridge / trade / withdraw tickets). Keep /guides/open-the-dex as the CTA-only child. Do not put this manuscript on / (that is the Start Here ecosystem map, code/cl8y-docs#9).

v0 platform work (#3) already shipped crawl files, unique titles, and stub routes. Full guide manuscripts were out of scope there. This issue is the first approved how-to.

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 + diagram + token purposes). Explicitly not a trading tutorial and not wallet UI. Cite and link; do not expand that ticket.
  • 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 and bridge fee presentation. Read, do not vendor unpublished internals.
  • code/cl8y-dex-terraclassic — swap UI the walkthrough points at; do not copy the SPA into this host.
  • code/CL8Y-web#1 — CL8Y utility-token wording. Different deployable.

Current codebase

How-to surface is a CTA stub, not a first-use guide:

  • src/pages/OpenDexPage.tsx — heading “Open the DEX”; copy: “This is not a trading tutorial, and it does not ask for a wallet connection on this host.” dexHref campaign guides-open-the-dex.
  • src/pages/GuidesPage.tsx — index lists only that one child. Copy forbids dumping unpublished marketing manuscripts.
  • src/seo.ts — closed DocsPath union of seven v0 paths. No first-use route.
  • src/lib/dexHref.ts — CAMPAIGNS closed vocabulary; no guides-first-use.
  • 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 + src/verify-dist.test.ts — unique titles/canonicals for the seven v0 paths; sitemap loc count follows ROUTES.
  • Architecture §4: /guides/open-the-dex purpose is “follow the first-party CTA. Not a trading tutorial.”

A complete first-use 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 (would contradict #3 copy and the CTA-only skill). Do not add /guides/start-here (reserved conceptually for #9 on /).

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 engineering problem (what exists vs how to use it)
Unpublished marketing content/guides/ Forbidden to dump here (INVARIANTS 14)
DEX / Bridge SPAs Cite live first-party UIs; do not copy wallet/swap/bridge screens into this repo as apps

If /guides/first-use already exists as a complete prerendered walkthrough (wallet → gas → inbound → first swap → outbound, sourced routes/fee kinds, common mistakes) 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 newcomers. Today the only guide child opens the DEX and stops. Without a first-use walkthrough:

  • Readers still lack wallet, gas, and inbound-asset steps before a swap can succeed.
  • Bridge inbound/outbound is unnamed on /guides.
  • Fee and route questions get answered in chat with no crawlable first-party page.

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

Constraints / guardrails

  1. Route. Add exactly one path: /guides/first-use. Title seed First use · Guides · CL8Y docs (wordsmith OK; must stay unique vs the other seven after #9’s home title change). Canonical https://docs.cl8y.com/guides/first-use (no trailing slash). Amend ARCHITECTURE §4 in the same PR. Do not add further children (no /guides/wallet, /guides/bridge, /guides/withdraw).
  2. Reader. Zero prior knowledge. Numbered steps. Short sentences. One scrollable manuscript with in-page headings (Wallet, Gas, Inbound, First trade, Outbound, Routes and costs, Common mistakes). Not a whitepaper. Not a Start Here product map (#9).
  3. This host stays static. INVARIANTS 19: no wagmi, WalletConnect, three.js, LCD keys, or DEX/bridge screens running here. The walkthrough describes using Station (or whatever wallets the live first-party DEX/Bridge already document). Do not mint a wallet directory. Do not ask the reader to connect a wallet on docs.cl8y.com.
  4. Gas. State clearly that Terra Classic execution needs native LUNC (uluna), distinct from CW20 cLUNC wrap legs. Do not invent a CEX list or “Buy CL8Y” as the gas path. If a first-party Bridge route can deliver LUNC, say so and link the Bridge; otherwise: gas is native LUNC, this host does not sell it, see Bridge / DEX for live options. Never present a third-party venue as the primary CTA.
  5. Inbound / outbound. First-party Bridge only: https://bridge.cl8y.com built with URL (not string concat, not window.location, not visitor query). rel="noopener noreferrer" if target="_blank". 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.
  6. First trade. Point at dexHref({ from: DEFAULT_FROM, to: DEFAULT_TO, campaign: "guides-first-use" }). Execute ids only (uluna + checksummed Terra Classic CL8Y CW20 already in src/data/contracts.ts). Copy must say: pick the pair, review quote on the DEX, confirm in the wallet on the DEX origin. This host does not broadcast. Do not deep-link slippage / expertMode / recipient / gems. Do not claim the DEX keeps utm_* after canonicalize (ARCHITECTURE §10).
  7. Fees and costs. Name the kinds: Terra Classic gas, Bridge fee (if the Bridge UI shows one), DEX swap fee / CL8Y fee-tier pointer. Do not print percentages, USD, TVL, volume, or ranking unless that exact figure already exists as a first-party constant in this repo (it does not today). Pattern: “the live DEX / Bridge UI shows the current fee; this page does not freeze a number.” No CoinGecko/CMC/DeFiLlama. No fabricated tier tables (code/CL8Y-web#1: point at the DEX for the live schedule).
  8. Screenshots (optional but in-scope). Same-origin files only (public/guides/first-use/ or equivalent). First-party Bridge and DEX 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 and omit images rather than invent UI.
  9. 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; do not add them here (that exception is #9’s CMM section on / only).
  10. CTAs. DEX via dexHref + new campaign guides-first-use (extend CAMPAIGNS). Bridge via tested helper/constant. Do not concatenate visitor query. No javascript: / data: / protocol-relative / ?url= redirectors. Tickers must never appear as execute ids.
  11. Guides index. /guides lists First use beside Open the DEX. One-line each; do not duplicate the manuscript on the index.
  12. Home. Optional one-line link from / once #9’s Start Here exists; not required to block this PR. Do not redefine / in this issue.
  13. Sitemap / nginx. Loc count becomes eight (seven v0 + this path) unless #9 already shipped without adding a path (it must not). nginx try_files unchanged. Unknown paths still 404. Do not change Dockerfile, Woodpecker shape, or DEX Sitemap: pointer.
  14. Do not publish ops internals, queue ids, host/SKU, or extra contract strings beyond src/data/contracts.ts.

Relevant files

Path Why
src/pages/FirstUsePage.tsx (new) Walkthrough manuscript
src/content/firstUse.ts (new, preferred) Strings + step ids so unit tests can forbid hype / unverified fee figures without rendering React
src/pages/GuidesPage.tsx Index link to /guides/first-use
src/App.tsx Register the route
src/seo.ts New DocsPath, title, description, campaign
src/lib/dexHref.ts + dexHref.test.ts Add guides-first-use to CAMPAIGNS
src/lib/ (Bridge helper if not already added by #9) new URL("/", "https://bridge.cl8y.com") + unit tests
src/data/contracts.ts Reuse CL8Y CW20; do not invent
src/content/invariants.ts Unchanged bans; first-use copy must still fail closed
e2e/crawl.spec.ts Eighth path: unique title/canonical; body sniff for required headings
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 figures; still no wallet UI
skills/docs-static-host/SKILL.md / docs-dex-cta New path + campaign
public/guides/first-use/ Optional screenshots
code/cl8y-bridge-monorepo Read published routes only
code/cl8y-docs#9 Sibling Start Here; do not merge manuscripts

Recommended direction

  1. Extract copy into src/content/firstUse.ts (step titles + body strings + “fee kinds” sentences with no numeric literals unless sourced). Unit-test: banned hype, no javascript:, no ticker execute ids, no unverified % / TVL.
  2. FirstUsePage: H1 First use; ordered sections; DEX CTA through dexHref; Bridge CTA through URL helper; common-mistakes list (wrong chain, missing gas, confusing LUNC vs cLUNC, sending Terra bech32 to an EVM field, treating docs as a wallet).
  3. Extend DocsPath / CAMPAIGNS / App / prerender. Sitemap is generated from seo.ts — do not hand-edit a second allowlist that can drift.
  4. GuidesPage: second stub line “First use — wallet, gas, inbound, first swap, outbound.”
  5. Playwright: prerendered HTML (no JS) contains the five phase headings; crawl MIME tests unchanged; 404 still 404.
  6. Do not change nginx, Dockerfile, or add WalletConnect.

Acceptance criteria

  • AC1. GET /guides/first-use prerendered HTML (no JS) contains a First use heading and the five phases: wallet, gas (uluna / LUNC), inbound Bridge, first DEX swap, outbound Bridge.
  • AC2. The same HTML contains a routes/costs section that names fee kinds and points at live Bridge/DEX UI; it contains no invented percentages, USD, TVL, volume, or ranking.
  • AC3. The same HTML contains a common-mistakes section covering at least: missing native gas, LUNC vs cLUNC, wrong chain / wrong address format.
  • AC4. DEX CTA uses dexHref with from=uluna, to= the Terra Classic CL8Y CW20 in contracts.ts, utm_campaign=guides-first-use. No tickers as execute ids.
  • 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 (First use · Guides · CL8Y docs or equivalent); canonical https://docs.cl8y.com/guides/first-use. Other v0 routes keep their titles (home may change only via #9).
  • AC7. /guides links to /guides/first-use. /guides/open-the-dex still exists and still is not rewritten into this manuscript.
  • AC8. Sitemap loc count 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/first-use. CAMPAIGNS includes guides-first-use.

Given a newcomer opens the prerendered /guides/first-use page
When they read the walkthrough without executing JavaScript
Then they can follow wallet setup, obtain native LUNC gas, bring funds in via the first-party Bridge, open the default DEX pair through dexHref, and move funds out via the Bridge, with sourced routes and fee kinds and without invented statistics or a wallet UI on this host

Test plan (functional paths)

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

Test plan (copy safety)

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

# Vector Expect
C1 Unverified TVL/volume/fee % 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/DEX 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 Tickers LUNC/CL8Y as from/to execute ids dexHref throw / test fail
C11 Teaching users to connect a wallet on docs.cl8y.com Forbidden (connect on DEX/Bridge origins only)
C12 Expanding #9’s / into this how-to Out of scope; fail review if this PR rewrites Start Here

Verification criteria

  • npm test && npm run typecheck && production npm run build with required VITE_*.
  • npm run test:dist (unique titles/canonicals including the eighth path).
  • Playwright 5 workers: first-use body sniff for the five phase headings; crawl MIME tests unchanged.
  • Human: open prerendered /guides/first-use and confirm a newcomer can answer “what do I do first / where does gas come from / how do I get funds in / where do I swap / how do I get funds out?” 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).
  • Replacing /guides/open-the-dex or adding more than one new path.
  • Wallet connect, swap execution, wrap/mint UI, pair create on this host.
  • Publishing unpublished marketing manuscripts.
  • Inventing DEX fee-tier tables, Bridge fee percentages, 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.

First-pass model recommendation

Recommendation: grok-high

Rationale: This is a newcomer how-to that spans wallet setup, Terra Classic gas, Bridge inbound/outbound, and a first DEX swap, plus a closed-allowlist expansion (DocsPath, CAMPAIGNS, prerender, sitemap, ARCHITECTURE §4). Composer’s docs/test-only path does not apply: wallet is a founder-required topic, product claims (routes, fee kinds) must be sourced from Bridge/DEX without inventing numbers, and the change is more than three local production files in one helper (FirstUsePage, firstUse copy module, seo/campaigns, App, guides index, architecture/invariants, crawl tests). Uncertain published-route/fee presentation on the Bridge 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/open-the-dex` is a first-party CTA stub: it tells the reader to open the DEX and explicitly is not a trading tutorial. A newcomer who has no wallet, no Terra Classic gas, and no assets on the right chain still cannot go from that page to a completed first use of CL8Y. Ship **one** prerendered first-user walkthrough on a **new** allowlisted path so a reader with nothing set up can follow a single manuscript through: 1. Wallet setup (compatible Terra Classic wallet; **describe**, do not embed a wallet UI on this host). 2. Obtaining the required gas token (native LUNC / `uluna`). 3. Bringing supported funds into the ecosystem via the first-party Bridge. 4. Completing a first swap on the first-party DEX (default pair: `uluna` → Terra Classic CL8Y CW20). 5. Moving funds back out via the Bridge. 6. Supported routes, fee **kinds**, common mistakes, and optional first-party screenshots. Bundle (do not split into wallet / gas / bridge / trade / withdraw tickets). Keep `/guides/open-the-dex` as the CTA-only child. Do not put this manuscript on `/` (that is the Start Here ecosystem map, `code/cl8y-docs`#9). v0 platform work (#3) already shipped crawl files, unique titles, and stub routes. Full guide manuscripts were out of scope there. This issue is the first approved **how-to**. 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 + diagram + token purposes). Explicitly not a trading tutorial and not wallet UI. Cite and link; do not expand that ticket. - `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 and bridge fee presentation. Read, do not vendor unpublished internals. - `code/cl8y-dex-terraclassic` — swap UI the walkthrough points at; do not copy the SPA into this host. - `code/CL8Y-web`#1 — CL8Y utility-token wording. Different deployable. ## Current codebase How-to surface is a CTA stub, not a first-use guide: - `src/pages/OpenDexPage.tsx` — heading “Open the DEX”; copy: “This is not a trading tutorial, and it does not ask for a wallet connection on this host.” `dexHref` campaign `guides-open-the-dex`. - `src/pages/GuidesPage.tsx` — index lists only that one child. Copy forbids dumping unpublished marketing manuscripts. - `src/seo.ts` — closed `DocsPath` union of seven v0 paths. No first-use route. - `src/lib/dexHref.ts` — `CAMPAIGNS` closed vocabulary; no `guides-first-use`. - `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` + `src/verify-dist.test.ts` — unique titles/canonicals for the seven v0 paths; sitemap loc count follows `ROUTES`. - Architecture §4: `/guides/open-the-dex` purpose is “follow the first-party CTA. Not a trading tutorial.” A complete first-use 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` (would contradict #3 copy and the CTA-only skill). Do not add `/guides/start-here` (reserved conceptually for #9 on `/`). ### 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 engineering problem (what exists vs how to use it) | | Unpublished marketing `content/guides/` | Forbidden to dump here (INVARIANTS 14) | | DEX / Bridge SPAs | Cite live first-party UIs; do not copy wallet/swap/bridge screens into this repo as apps | If `/guides/first-use` already exists as a complete prerendered walkthrough (wallet → gas → inbound → first swap → outbound, sourced routes/fee kinds, common mistakes) 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 newcomers. Today the only guide child opens the DEX and stops. Without a first-use walkthrough: - Readers still lack wallet, gas, and inbound-asset steps before a swap can succeed. - Bridge inbound/outbound is unnamed on `/guides`. - Fee and route questions get answered in chat with no crawlable first-party page. This is documentation copy + one new prerendered route + optional same-origin screenshots. No wallet SDK, no swap execution on this host, no Coolify SKU pick. ## Constraints / guardrails 1. **Route.** Add exactly one path: `/guides/first-use`. Title seed `First use · Guides · CL8Y docs` (wordsmith OK; must stay unique vs the other seven after #9’s home title change). Canonical `https://docs.cl8y.com/guides/first-use` (no trailing slash). Amend ARCHITECTURE §4 in the same PR. Do not add further children (no `/guides/wallet`, `/guides/bridge`, `/guides/withdraw`). 2. **Reader.** Zero prior knowledge. Numbered steps. Short sentences. One scrollable manuscript with in-page headings (Wallet, Gas, Inbound, First trade, Outbound, Routes and costs, Common mistakes). Not a whitepaper. Not a Start Here product map (#9). 3. **This host stays static.** INVARIANTS 19: no wagmi, WalletConnect, three.js, LCD keys, or DEX/bridge screens **running here**. The walkthrough **describes** using Station (or whatever wallets the live first-party DEX/Bridge already document). Do not mint a wallet directory. Do not ask the reader to connect a wallet on `docs.cl8y.com`. 4. **Gas.** State clearly that Terra Classic execution needs native LUNC (`uluna`), distinct from CW20 `cLUNC` wrap legs. Do not invent a CEX list or “Buy CL8Y” as the gas path. If a first-party Bridge route can deliver LUNC, say so and link the Bridge; otherwise: gas is native LUNC, this host does not sell it, see Bridge / DEX for live options. Never present a third-party venue as the primary CTA. 5. **Inbound / outbound.** First-party Bridge only: `https://bridge.cl8y.com` built with `URL` (not string concat, not `window.location`, not visitor query). `rel="noopener noreferrer"` if `target="_blank"`. 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. 6. **First trade.** Point at `dexHref({ from: DEFAULT_FROM, to: DEFAULT_TO, campaign: "guides-first-use" })`. Execute ids only (`uluna` + checksummed Terra Classic CL8Y CW20 already in `src/data/contracts.ts`). Copy must say: pick the pair, review quote on the DEX, confirm in the wallet **on the DEX origin**. This host does not broadcast. Do not deep-link `slippage` / `expertMode` / `recipient` / gems. Do not claim the DEX keeps `utm_*` after canonicalize (ARCHITECTURE §10). 7. **Fees and costs.** Name the **kinds**: Terra Classic gas, Bridge fee (if the Bridge UI shows one), DEX swap fee / CL8Y fee-tier **pointer**. Do **not** print percentages, USD, TVL, volume, or ranking unless that exact figure already exists as a first-party constant in this repo (it does not today). Pattern: “the live DEX / Bridge UI shows the current fee; this page does not freeze a number.” No CoinGecko/CMC/DeFiLlama. No fabricated tier tables (`code/CL8Y-web`#1: point at the DEX for the live schedule). 8. **Screenshots (optional but in-scope).** Same-origin files only (`public/guides/first-use/` or equivalent). First-party Bridge and DEX 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 and omit images rather than invent UI. 9. **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; do not add them here (that exception is #9’s CMM section on `/` only). 10. **CTAs.** DEX via `dexHref` + new campaign `guides-first-use` (extend `CAMPAIGNS`). Bridge via tested helper/constant. Do not concatenate visitor query. No `javascript:` / `data:` / protocol-relative / `?url=` redirectors. Tickers must never appear as execute ids. 11. **Guides index.** `/guides` lists First use beside Open the DEX. One-line each; do not duplicate the manuscript on the index. 12. **Home.** Optional one-line link from `/` once #9’s Start Here exists; not required to block this PR. Do not redefine `/` in this issue. 13. **Sitemap / nginx.** Loc count becomes eight (seven v0 + this path) unless #9 already shipped without adding a path (it must not). nginx `try_files` unchanged. Unknown paths still 404. Do not change Dockerfile, Woodpecker shape, or DEX `Sitemap:` pointer. 14. **Do not** publish ops internals, queue ids, host/SKU, or extra contract strings beyond `src/data/contracts.ts`. ## Relevant files | Path | Why | | --- | --- | | `src/pages/FirstUsePage.tsx` (new) | Walkthrough manuscript | | `src/content/firstUse.ts` (new, preferred) | Strings + step ids so unit tests can forbid hype / unverified fee figures without rendering React | | `src/pages/GuidesPage.tsx` | Index link to `/guides/first-use` | | `src/App.tsx` | Register the route | | `src/seo.ts` | New `DocsPath`, title, description, campaign | | `src/lib/dexHref.ts` + `dexHref.test.ts` | Add `guides-first-use` to `CAMPAIGNS` | | `src/lib/` (Bridge helper if not already added by #9) | `new URL("/", "https://bridge.cl8y.com")` + unit tests | | `src/data/contracts.ts` | Reuse CL8Y CW20; do not invent | | `src/content/invariants.ts` | Unchanged bans; first-use copy must still fail closed | | `e2e/crawl.spec.ts` | Eighth path: unique title/canonical; body sniff for required headings | | `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 figures; still no wallet UI | | `skills/docs-static-host/SKILL.md` / `docs-dex-cta` | New path + campaign | | `public/guides/first-use/` | Optional screenshots | | `code/cl8y-bridge-monorepo` | Read published routes only | | `code/cl8y-docs`#9 | Sibling Start Here; do not merge manuscripts | ## Recommended direction 1. Extract copy into `src/content/firstUse.ts` (step titles + body strings + “fee kinds” sentences with no numeric literals unless sourced). Unit-test: banned hype, no `javascript:`, no ticker execute ids, no unverified `%` / TVL. 2. `FirstUsePage`: H1 First use; ordered sections; DEX CTA through `dexHref`; Bridge CTA through URL helper; common-mistakes list (wrong chain, missing gas, confusing LUNC vs cLUNC, sending Terra bech32 to an EVM field, treating docs as a wallet). 3. Extend `DocsPath` / `CAMPAIGNS` / `App` / prerender. Sitemap is generated from `seo.ts` — do not hand-edit a second allowlist that can drift. 4. `GuidesPage`: second stub line “First use — wallet, gas, inbound, first swap, outbound.” 5. Playwright: prerendered HTML (no JS) contains the five phase headings; crawl MIME tests unchanged; 404 still 404. 6. Do not change nginx, Dockerfile, or add WalletConnect. ## Acceptance criteria - AC1. `GET /guides/first-use` prerendered HTML (no JS) contains a First use heading and the five phases: wallet, gas (`uluna` / LUNC), inbound Bridge, first DEX swap, outbound Bridge. - AC2. The same HTML contains a routes/costs section that names fee **kinds** and points at live Bridge/DEX UI; it contains **no** invented percentages, USD, TVL, volume, or ranking. - AC3. The same HTML contains a common-mistakes section covering at least: missing native gas, LUNC vs cLUNC, wrong chain / wrong address format. - AC4. DEX CTA uses `dexHref` with `from=uluna`, `to=` the Terra Classic CL8Y CW20 in `contracts.ts`, `utm_campaign=guides-first-use`. No tickers as execute ids. - 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 (`First use · Guides · CL8Y docs` or equivalent); canonical `https://docs.cl8y.com/guides/first-use`. Other v0 routes keep their titles (home may change only via #9). - AC7. `/guides` links to `/guides/first-use`. `/guides/open-the-dex` still exists and still is not rewritten into this manuscript. - AC8. Sitemap loc count 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/first-use`. `CAMPAIGNS` includes `guides-first-use`. Given a newcomer opens the prerendered `/guides/first-use` page When they read the walkthrough without executing JavaScript Then they can follow wallet setup, obtain native LUNC gas, bring funds in via the first-party Bridge, open the default DEX pair through `dexHref`, and move funds out via the Bridge, with sourced routes and fee kinds and without invented statistics or a wallet UI on this host ## Test plan (functional paths) | # | Path | Expect | | --- | --- | --- | | T1 | `dist/guides/first-use/index.html` | Unique title/canonical; First use H1 | | T2 | Same file, no JS | Headings for wallet, gas, inbound, first trade, outbound | | T3 | Same file | Routes/costs copy present; no `%` fee table unless sourced constant | | T4 | DEX anchor | `dexHref` default pair + `utm_campaign=guides-first-use` | | T5 | Bridge anchor | `https://bridge.cl8y.com`; `rel` safe if new tab | | T6 | `/guides` HTML | Link to `/guides/first-use` | | T7 | `/guides/open-the-dex` | Still CTA-only; not replaced | | T8 | `GET /guides/wallet` (unlisted) | 404 | | T9 | Unit: `firstUse.ts` | Forbidden claim patterns fail if someone pastes TVL / “best DEX” / fee `%` | | T10 | Playwright 5 workers | New path in crawl table; previous seven still pass | ## Test plan (copy safety) Not a DeFi attack suite. Keep host crawl/CTA tests from #3 green. | # | Vector | Expect | | --- | --- | --- | | C1 | Unverified TVL/volume/fee % 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/DEX 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 | Tickers `LUNC`/`CL8Y` as `from`/`to` execute ids | `dexHref` throw / test fail | | C11 | Teaching users to connect a wallet **on docs.cl8y.com** | Forbidden (connect on DEX/Bridge origins only) | | C12 | Expanding #9’s `/` into this how-to | Out of scope; fail review if this PR rewrites Start Here | ## Verification criteria - `npm test` && `npm run typecheck` && production `npm run build` with required `VITE_*`. - `npm run test:dist` (unique titles/canonicals including the eighth path). - Playwright 5 workers: first-use body sniff for the five phase headings; crawl MIME tests unchanged. - Human: open prerendered `/guides/first-use` and confirm a newcomer can answer “what do I do first / where does gas come from / how do I get funds in / where do I swap / how do I get funds out?” 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). - Replacing `/guides/open-the-dex` or adding more than one new path. - Wallet connect, swap execution, wrap/mint UI, pair create **on this host**. - Publishing unpublished marketing manuscripts. - Inventing DEX fee-tier tables, Bridge fee percentages, 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. ## First-pass model recommendation Recommendation: grok-high Rationale: This is a newcomer how-to that spans wallet setup, Terra Classic gas, Bridge inbound/outbound, and a first DEX swap, plus a closed-allowlist expansion (`DocsPath`, `CAMPAIGNS`, prerender, sitemap, ARCHITECTURE §4). Composer’s docs/test-only path does not apply: wallet is a founder-required topic, product claims (routes, fee kinds) must be sourced from Bridge/DEX without inventing numbers, and the change is more than three local production files in one helper (`FirstUsePage`, `firstUse` copy module, seo/campaigns, App, guides index, architecture/invariants, crawl tests). Uncertain published-route/fee presentation on the Bridge 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#10
No description provided.