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

docs(guides): token and treasury mechanics FAQ #13

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

Summary

https://docs.cl8y.com has no crawlable first-party FAQ that explains token and treasury mechanics in plain English. Start Here (code/cl8y-docs#9) is allowed purpose lines only and explicitly forbids collateral ratios, circulating supply, and APY. Users and marketers still confuse USTC vs USTR vs UST1, conversion windows, what backs each asset, what burning cLUNC actually does on-chain, and how treasury ratio accounting avoids wrap double counting.

Ship one prerendered Token and treasury FAQ on the architecture-reserved UST1 path so support can paste a stable URL instead of rewriting the same answers in chat.

Bundle (do not split into ticker / window / wrap / CR tickets):

  1. Asset glossary — USTC, USTR, UST1, plus the wrap legs needed to tell the truth (native LUNC / uluna, cLUNC, cUSTC). Native USTC (uusd) is Terra Classic, not a CMM-issued CW20.
  2. Conversion windows — the time-limited USTC→USTR swap versus the UST1 mint/redeem window (vFDUSD ↔ UST1). Name them as distinct contracts/jobs.
  3. Backing — what each named asset is (legacy native, equity/governance, collateralized unstablecoin, wrap receipt). No invented 1:1 or “fully backed” slogans.
  4. cLUNC burn/unwrap — what the wrap-mapper (and only that path) does when cLUNC is redeemed; not a DEX fee-tier burn and not a USTR buyback.
  5. Treasury ratios / no double count — plain-English CR CMM Assets vs CR CMM Liabilities, USTR as equity (not a CR liability), wrap inventory not counted twice. Point at the live CMM Treasury page for live figures; do not freeze CR%, APY, remaining window days, or fee bps unless that exact figure already exists as a first-party constant in this repo (it does not today).

Keep / as Start Here (code/cl8y-docs#9). Do not put this manuscript on /guides/first-use (#10), /guides/bridge (#11), or /guides/dex (#12). DEX /wrap remains #12.

v0 platform work (#3) already shipped crawl files, unique titles, and stub routes. Full manuscripts were out of scope there. Architecture §4 already names a future UST1 page as a separate approved issue — this is that issue, written as a FAQ rather than a ticker landing page.

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 /. Purpose lines only; no CR/supply/APY; forbids adding /ust1 in that PR. Cite and link; do not expand that ticket.
  • code/cl8y-docs#10 / #11 / #12 — how-to manuscripts. Different reader jobs. Those PRs must not register /ust1.
  • docs/ARCHITECTURE.md §4 / §12 — closed route allowlist; “A future UST1 page is a separate approved issue”; BANNED_CURRENT_COPY includes UST1 / USTR; no unverified stats; no unpublished marketing content/guides/.
  • code/ustr-cmm — CMM product tree (README, docs/ARCHITECTURE.md, docs/ECONOMICS.md, docs/CONTRACTS.md, frontend/src/utils/treasuryRatios.ts, skills/frontend-ust1-ratios). Source of names and CR accounting pins. Read; do not vendor the economics whitepaper or operator runbooks onto this host.
  • code/ust1-window — UST1 window + oracle/wrap packages. Source of mint/redeem window mechanics. Read; do not copy oracle-service ops, Coolify, or unpublished internals.
  • code/CL8Y-web#1 — CL8Y utility-token wording. Different deployable.

Current codebase

No FAQ route; CMM tickers are banned on current-product copy so v0 stubs cannot revive old marketing:

  • src/pages/GuidesPage.tsx — lists only /guides/open-the-dex. Copy forbids dumping unpublished marketing manuscripts.
  • src/pages/HomePage.tsx — host chrome today; #9 will become Start Here with purpose lines only (no CR).
  • src/pages/MethodologyPage.tsx — how numbers on this host are sourced; not a token glossary.
  • src/pages/ContractsPage.tsx + src/data/contracts.ts — Terra Classic CL8Y CW20, CL8Y/cLUNC pair, BSC CL8Y, MegaETH CL8Y, native uluna. No USTR / UST1 / wrap-mapper / treasury addresses.
  • src/seo.ts — closed DocsPath union of seven v0 paths. No /ust1.
  • src/lib/dexHref.ts — CAMPAIGNS closed vocabulary; no ust1 / guides-token-treasury.
  • src/App.tsx — seven Route entries; unknown paths 404 via nginx try_files … =404.
  • src/content/invariants.ts — BANNED_CURRENT_COPY includes UST1, USTR; FORBIDDEN_CLAIM_PATTERNS bans TVL / “best DEX” / CoinGecko / CMC / DeFiLlama.
  • e2e/crawl.spec.ts — currently hardcodes the seven v0 paths (must follow ROUTES after this path is added; do not assume loc count 7/8/9 if #9–#12 land first).
  • src/verify-dist.test.ts — follows ROUTES; sitemap loc count follows that module.
  • Architecture §4: no UST1 FAQ row; future UST1 page called out as a later issue.

A complete FAQ therefore must add one allowlisted path in the same PR (seo union, campaign id, App route, prerender, sitemap, crawl tests, ARCHITECTURE §4, bounded BANNED_CURRENT_COPY exception). Do not add /ustr, /ustc, /guides/ust1, /guides/ustr, or /guides/faq as extra routes — support deep-links are in-page fragment ids on the one manuscript.

Duplicates / already implemented

Work Action
#1 architecture, #2 review, #5 CI Unrelated; do not reopen
#3 v0 stubs Prerequisite host
#9 Start Here on / Sibling map; purpose lines only. Different problem. That PR must not register /ust1.
#10 first-use / #11 Bridge / #12 DEX how-to Sibling how-tos. #12 may mention DEX wrap; it must not teach CMM treasury CR or USTC→USTR windows.
Unpublished marketing content/guides/ Forbidden to dump here (INVARIANTS 14)
code/ustr-cmm Treasury SPA Cite the live UI for live CR; do not copy the dashboard into this host
code/ustr-cmm docs/ECONOMICS.md Source of design rationale. Do not paste the whitepaper, auction theory, or 5-year pool manuscript onto docs.cl8y.com
code/ust1-window operator / oracle tickets Different repo; this page is a retail FAQ, not an oracle runbook

If /ust1 already exists as a complete prerendered FAQ (glossary, windows, backing, cLUNC unwrap/burn, CR no-double-count, sourced addresses only, unique title/canonical) 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 mix up USTC, USTR, and UST1. Today:

  • / will map products (#9) without explaining conversion windows, backing, unwrap, or CR accounting.
  • /methodology only says figures must be first-party; it does not define the assets.
  • /contracts lists CL8Y addresses, not CMM treasury/window/wrap.
  • Chat answers invite invented “fully backed,” frozen CR%, and “burning cLUNC” as a DEX deflation story.

This is documentation copy + one new prerendered route + copy-safety tests. No wallet UI, no treasury dashboard, no Coolify SKU pick.

Constraints / guardrails

  1. Route. Add exactly one path: /ust1 (architecture-reserved). Title seed Token and treasury FAQ · CL8Y docs (wordsmith OK; must stay unique vs / after #9 and vs #10–#12). Canonical https://docs.cl8y.com/ust1 (no trailing slash). Amend ARCHITECTURE §4 in the same PR. Do not add /ustr, /ustc, or extra children. In-page fragments for support paste: #ustc-vs-ustr-vs-ust1, #conversion-windows, #backing, #clunc-burn, #treasury-ratios.

  2. Reader. Users and marketers. Short sentences. FAQ headings as questions. Not a whitepaper. Not a Start Here product map (#9). Not a trading tutorial (#10/#12).

  3. This host stays static. INVARIANTS 19: no wagmi, WalletConnect, LCD keys, or CMM/DEX screens running here. Do not embed live CR. Point at the first-party CMM Treasury UI for live ratios and at /methodology for “this host does not freeze protocol statistics.”

  4. Banned-copy exception (bounded). Allow UST1, USTR, and USTC as factual names on /ust1 (and tests for that page / copy module). Keep the ban on GameFi lore, “Buy CL8Y” as a CTA, “the future of DeFi”, TVL, “best DEX”, CoinGecko/CMC/DeFiLlama. Do not leak those tickers onto /methodology stubs via shared layout. Do not add /ustr as a route just because the FAQ names USTR.

  5. Glossary (required distinctions). Wordsmith OK; do not collapse these into one “UST” story:

    Name What to say (intent) Source
    USTC Terra Classic native (uusd). Legacy network asset. Not UST1. Not USTR. Terra Classic; CMM swap takes USTC in
    USTR CMM utility/governance CW20 acquired via the time-limited USTC→USTR swap. Equity: no redemption in CR math code/ustr-cmm README; skills/frontend-ust1-ratios pin 1
    UST1 CMM collateralized CW20 unstablecoin; minted/burned via ust1-window against treasury collateral (vFDUSD path) ustr-cmm README; code/ust1-window README
    LUNC / uluna Terra Classic native ARCHITECTURE §4
    cLUNC CW20 wrap of LUNC via CMM wrap-mapper (DEX pair legs may use it; that is not this FAQ’s wrap lesson) ustr-cmm README wrap-mapper / cLUNC row
    cUSTC CW20 wrap of USTC via wrap-mapper same

    Do not list GameFi / PROTOCASS / Karnyx / TigerHunt. Do not lead with memecoin / Autoscarcity.

  6. Conversion windows (required). Two different windows. Do not describe a single “conversion window”:

    • USTC→USTR swap (ustc-swap): time-limited, time-decaying rate; USTC flows to treasury; USTR is minted to the user. Do not freeze start/end calendar days, remaining days, or 1.5→2.5 rates unless those exact figures are already first-party constants in this repo. Prefer: name the mechanism, then “see the live CMM swap UI for the current rate and whether the window is open.”
    • UST1 window (ust1-window): deposit vFDUSD → mint UST1 (forward collateral to treasury); withdraw burns UST1 and pulls collateral. Oracle/rate policy exists on that product; this FAQ may say a published rate is used and can pause — it must not document operator poll intervals, heartbeat, or Coolify.

    If a window is closed on-chain at implement time, say so in past tense from a sourced first-party sentence; do not invent reopen dates.

  7. Backing. Explain economic role, not slogans:

    • USTC is not “backed by” CMM; CMM accepts it into treasury via the swap.
    • USTR is not a redeemable stable; it is not a CR liability (frontend-ust1-ratios pin 1).
    • UST1 is collateralized; circulating/available supply and CR are live Treasury figures, not docs constants.
    • cLUNC/cUSTC are wrap receipts for native LUNC/USTC, not a second independent reserve that should be added on top of the native already in CR assets.

    Forbidden: “fully backed 1:1,” “algorithmic stablecoin,” APY, TVL, fabricated collateral-ratio percentages, CoinGecko proof.

  8. Burning cLUNC. Required honest sentence: redeeming/unwrapping cLUNC burns the CW20 and returns native LUNC (minus protocol wrap/unwrap fees as implemented by wrap-mapper). That is not:

    • burning CL8Y,
    • a DEX trading-fee burn,
    • destroying native LUNC off-chain,
    • the UST1 window burn (that burns UST1).

    Distinguish CMM wrap-mapper (cLUNC/cUSTC) from DEX /wrap (#12) and from cmm-native-wrap (wLUNC/wUSTC in ust1-window) in one short “related wraps” note so marketers do not merge them. Do not freeze fee_bps / unwrap all-in % unless already a constant in this repo.

  9. Treasury ratios / double counting (required). Translate skills/frontend-ust1-ratios into plain English. Must hold in copy:

    • CR% = (CR CMM Assets / CR CMM Liabilities) × 100.
    • Liabilities for CR = available UST1 (as $1 debt) + cUSTC + cLUNC inventories — not raw total_supply alone, not window volume, not USTR.
    • USTR is equity (no redemption) and is omitted from CR liabilities.
    • No wrap double-count: raw cLUNC/cUSTC are not CR assets (native LUNC/USTC already count). Protocol LP wrap legs belong in Total/display NAV, not crUsd.
    • UST1 held by CMM is not a CR asset.
    • Docs must not print a live CR%, color tier (RED/YELLOW/GREEN/BLUE), or USD NAV. Point at the live Treasury page. Incomplete prices on that UI hide ratios — docs should not invent a substitute number.

    /methodology may gain a one-line pointer to this FAQ for CMM figures; do not move the FAQ onto /methodology.

  10. Addresses. Optional small table. Only strings already published first-party in code/ustr-cmm README and/or code/ust1-window README (USTR, UST1, treasury, wrap-mapper, cLUNC, cUSTC, ustc-swap, ust1-window). If shown, add them to src/data/contracts.ts in this PR and render from that module. Do not invent. Do not paste operator/deployer/oracle-operator keys as a user FAQ. Finder links: first-party or already used CMM pattern (finder.terraclassic.community/columbus-5); build with URL, not string concat.

  11. CTAs. Optional DEX CTA via dexHref with a new closed campaign id (e.g. ust1) — default pair remains uluna → Terra Classic CL8Y CW20 execute ids, not UST1 tickers as execute ids. CMM Treasury / CMM app href: first-party origin only, URL helper, rel="noopener noreferrer" if new tab. Do not make “Buy CL8Y” or “Buy UST1” the primary button. Do not deep-link third-party venues. Do not concatenate visitor query.

  12. Guides index. Link this FAQ from /guides (label Token and treasury FAQ). Optional one-line “mechanics FAQ” link from Start Here CMM section belongs in #9’s PR or a tiny follow-up after #9 lands — this PR must not rewrite / beyond a single optional link if / already has CMM copy; if #9 has not landed, do not take over HomePage.

  13. No wallet / mint UI. No wrap/mint/redeem forms. Describe using the live CMM UI.

  14. Do not publish ops internals, unpublished marketing manuscripts, oracle poll/silence env, or extra contract addresses.

Relevant files

Path Why
src/pages/ (new page) FAQ manuscript + fragment ids
src/pages/GuidesPage.tsx Link to /ust1
src/App.tsx Register the route
src/seo.ts DocsPath + ROUTES row; unique title/description
src/lib/dexHref.ts New closed campaign id if this page emits a DEX CTA
src/lib/ (small helper OK) First-party CMM origin URL builder + unit tests (reuse if #9/#10/#11 already added one)
src/content/invariants.ts Page-scoped UST1/USTR/USTC allow for /ust1 only
src/content/ (new copy module OK) FAQ strings so unit tests can forbid hype / frozen CR% / “fully backed”
src/data/contracts.ts Optional CMM addresses copied from published READMEs
e2e/crawl.spec.ts New path title/canonical; follow ROUTES
src/verify-dist.test.ts Sitemap loc count follows ROUTES
docs/ARCHITECTURE.md §4 / §12 UST1 FAQ row; document ticker-name exception
docs/INVARIANTS.md Same exception; still no unverified claims
code/ustr-cmm README + docs/ARCHITECTURE.md + skills/frontend-ust1-ratios Names, windows, CR pins (read, do not vendor)
code/ust1-window README UST1 window mint/burn vs vFDUSD (read, do not vendor)

Recommended direction

  1. Extract FAQ copy into src/content/tokenTreasuryFaq.ts (Q/A strings + optional address rows) so unit tests can forbid banned hype, fully backed, frozen CR% / APY / TVL, and GameFi lore without rendering React.
  2. New page: H1 Token and treasury FAQ; sections matching the five fragment ids; short “see live Treasury” sentence; guides back-link.
  3. Register /ust1 in seo.ts DocsPath / ROUTES, App.tsx, prerender list, sitemap rewrite. Campaign ust1 (or guides-token-treasury) added to CAMPAIGNS only if a DEX CTA is emitted.
  4. Scoped allowlist: UST1 / USTR / USTC permitted in the FAQ module / page tests only.
  5. If listing addresses, extend contracts.ts from published README strings; tests assert the page only emits those constants.
  6. Update ARCHITECTURE §4 (this is the approved UST1 page) and INVARIANTS copy-exception. Do not change nginx, Dockerfile, or Woodpecker shape.
  7. Do not land ECONOMICS.md wholesale. One FAQ page.

Acceptance criteria

  • AC1. GET /ust1 prerendered HTML (no JS) contains FAQ headings that distinguish USTC, USTR, and UST1.
  • AC2. The same HTML explains two conversion windows (USTC→USTR swap vs UST1 mint/redeem) as distinct, without freezing remaining days or rates unless those exact figures exist as constants in this repo.
  • AC3. The same HTML states what backs (or does not redeem) each named asset without “fully backed 1:1” / algorithmic-stable slogans.
  • AC4. The same HTML explains cLUNC unwrap as burning the CW20 to return native LUNC (minus wrap-mapper fees as sourced), and states that this is not a DEX CL8Y burn and not the UST1-window burn.
  • AC5. The same HTML explains CR assets vs liabilities, that USTR is omitted from CR liabilities, and that wrap inventory is not counted twice as a CR asset; it does not print a live CR% or USD NAV.
  • AC6. Unique title (Token and treasury FAQ · CL8Y docs or equivalent); canonical https://docs.cl8y.com/ust1. Other routes unchanged except /guides listing this child.
  • AC7. /guides links to /ust1 labeled as the token/treasury FAQ. No second new path.
  • AC8. No TVL / “best DEX” / CoinGecko / CMC / DeFiLlama / fabricated fee tiers / APY. GameFi lore absent. “Buy CL8Y” is not a CTA.
  • AC9. UST1 / USTR appear as factual names on this page (and its tests); they must not leak onto /methodology stub via shared layout.
  • AC10. Any contract strings on the page match src/data/contracts.ts after this PR (CL8Y set and/or published CMM strings added there). No invented addresses.
  • AC11. npm test, npm run typecheck, production npm run build with required VITE_*, dist unique-title tests, Playwright 5 workers stay green.
  • AC12. Unknown paths still 404; robots/sitemap MIME unchanged; sitemap locs remain this origin only.

Given a reader opens the prerendered /ust1 page
When they read the FAQ without executing JavaScript
Then they can tell USTC, USTR, and UST1 apart, describe the two conversion windows without invented remaining time, state backing/redemption honestly, explain cLUNC unwrap/burn versus other burns, and explain how CR accounting avoids wrap double counting, with a pointer to live first-party Treasury figures and no frozen unverified CR%/APY/TVL

Test plan (functional paths)

# Path Expect
T1 dist/ust1/index.html FAQ headings present; unique title/canonical
T2 Same file, no JS USTC, USTR, UST1 named as distinct; two windows named
T3 Same file cLUNC unwrap/burn sentence; CR no-double-count / USTR-not-liability sentence; no numeric CR%
T4 Fragment ids #ustc-vs-ustr-vs-ust1, #conversion-windows, #backing, #clunc-burn, #treasury-ratios exist as element ids
T5 /guides HTML Link to /ust1
T6 DEX CTA if present dexHref execute ids + new campaign; not ticker execute ids
T7 CMM Treasury href if present First-party origin; URL construction; safe rel if new tab
T8 /methodology, /markets, /contracts Still unique titles; not overwritten with this H1
T9 GET /ustr, GET /ustc, GET /guides/faq 404 (not shipped)
T10 GET /no-such-page 404
T11 Unit: copy module Forbidden claim patterns fail if someone pastes TVL / “fully backed” / APY / live CR%
T12 Playwright 5 workers New path assertions; previous crawl tests 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 % / CR% / APY on /ust1 Fail AC8 / unit grep
C2 GameFi / PROTOCASS / Karnyx / TigerHunt Absent
C3 Primary CTA “Buy CL8Y” / “Buy UST1” or third-party venue Forbidden
C4 javascript: / data: / protocol-relative CMM/DEX href Never emitted
C5 Visitor query concatenated onto CTA Forbidden
C6 New sitemap loc to a foreign host Forbidden
C7 Dump of unpublished marketing guides or ECONOMICS.md wholesale Forbidden
C8 USTR/UST1 on /methodology stub via shared layout Fail; exception is /ust1 copy only
C9 Invented contract not in contracts.ts Fail review
C10 Wallet/WC/treasury dashboard UI Fail review
C11 Collapsing USTC/USTR/UST1 into one “UST” Fail AC1
C12 Teaching DEX wrap as CMM wrap-mapper burn Fail AC4; point #12 for DEX wrap

Verification criteria

  • npm test && npm run typecheck && production npm run build with required VITE_*.
  • npm run test:dist (unique titles/canonicals; sitemap loc count = ROUTES.length).
  • Playwright 5 workers: /ust1 body sniff for glossary + window + unwrap + CR accounting headings; crawl MIME tests unchanged.
  • Human: open prerendered /ust1 and confirm a marketer can answer “is USTR the same as UST1?” and “does burning cLUNC delete LUNC or unwrap a CW20?” from the page alone.
  • scripts/check-origins.mjs still fail-closed without HTTPS origins.
  • No Coolify hostname/SKU work in this PR.

Out of scope

  • Extra docs routes (/ustr, /ustc, /guides/ust1), nginx, Dockerfile, Woodpecker shape, or DEX Sitemap: pointer.
  • Wallet connect, swap execution, wrap/mint/redeem UI, pair create.
  • Publishing unpublished marketing manuscripts or pasting ECONOMICS.md / auction / 5-year pool text.
  • Inventing or freezing live CR%, fee bps, window remaining days, or extra addresses.
  • Editing code/ustr-cmm, code/ust1-window, code/CL8Y-web, or the DEX SPA (read-only sources).
  • Implementing #9–#12 manuscripts.
  • Choosing hypervisor image, SKU, or a new host.

First-pass model recommendation

Recommendation: grok-high

Rationale: Public token/treasury copy must be sourced from code/ustr-cmm (CR pins, wrap-mapper, USTC→USTR swap) and code/ust1-window without inventing backing, rates, or CR%. It needs a new allowlisted route, a bounded BANNED_CURRENT_COPY exception for UST1/USTR/USTC, FAQ fragment ids, optional contracts.ts CMM addresses, seo/sitemap/crawl updates, and copy-safety tests. That is more than three production files in one helper and is not docs/test-only maintenance of an existing stub. Token/treasury accounting is founder-adjacent (contracts / wallet-adjacent product claims). Uncertain window-open status and which published rates may be printed fail the Composer rubric (known local edit, low ambiguity). Comparable control-plane calibration: a single RCA Markdown (#170) would be Composer; this spans content policy plus prerender routing more like a cross-module change than a test-helper tweak (#164).

## Summary `https://docs.cl8y.com` has no crawlable first-party FAQ that explains token and treasury mechanics in plain English. Start Here (`code/cl8y-docs`#9) is allowed purpose lines only and explicitly forbids collateral ratios, circulating supply, and APY. Users and marketers still confuse **USTC vs USTR vs UST1**, conversion windows, what backs each asset, what **burning cLUNC** actually does on-chain, and how treasury ratio accounting avoids wrap **double counting**. Ship one prerendered Token and treasury FAQ on the architecture-reserved UST1 path so support can paste a stable URL instead of rewriting the same answers in chat. Bundle (do not split into ticker / window / wrap / CR tickets): 1. Asset glossary — USTC, USTR, UST1, plus the wrap legs needed to tell the truth (native LUNC / `uluna`, cLUNC, cUSTC). Native USTC (`uusd`) is Terra Classic, not a CMM-issued CW20. 2. Conversion windows — the time-limited USTC→USTR swap versus the UST1 mint/redeem window (vFDUSD ↔ UST1). Name them as distinct contracts/jobs. 3. Backing — what each named asset is (legacy native, equity/governance, collateralized unstablecoin, wrap receipt). No invented 1:1 or “fully backed” slogans. 4. cLUNC burn/unwrap — what the wrap-mapper (and only that path) does when cLUNC is redeemed; not a DEX fee-tier burn and not a USTR buyback. 5. Treasury ratios / no double count — plain-English CR CMM Assets vs CR CMM Liabilities, USTR as equity (not a CR liability), wrap inventory not counted twice. Point at the live CMM Treasury page for live figures; do not freeze CR%, APY, remaining window days, or fee bps unless that exact figure already exists as a first-party constant in this repo (it does not today). Keep `/` as Start Here (`code/cl8y-docs`#9). Do not put this manuscript on `/guides/first-use` (#10), `/guides/bridge` (#11), or `/guides/dex` (#12). DEX `/wrap` remains #12. v0 platform work (#3) already shipped crawl files, unique titles, and stub routes. Full manuscripts were out of scope there. Architecture §4 already names a future UST1 page as a separate approved issue — this is that issue, written as a FAQ rather than a ticker landing page. 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 `/`. Purpose lines only; no CR/supply/APY; forbids adding `/ust1` in that PR. Cite and link; do not expand that ticket. - `code/cl8y-docs`#10 / #11 / #12 — how-to manuscripts. Different reader jobs. Those PRs must not register `/ust1`. - `docs/ARCHITECTURE.md` §4 / §12 — closed route allowlist; “A future UST1 page is a separate approved issue”; `BANNED_CURRENT_COPY` includes `UST1` / `USTR`; no unverified stats; no unpublished marketing `content/guides/`. - `code/ustr-cmm` — CMM product tree (README, `docs/ARCHITECTURE.md`, `docs/ECONOMICS.md`, `docs/CONTRACTS.md`, `frontend/src/utils/treasuryRatios.ts`, `skills/frontend-ust1-ratios`). Source of names and CR accounting pins. Read; do not vendor the economics whitepaper or operator runbooks onto this host. - `code/ust1-window` — UST1 window + oracle/wrap packages. Source of mint/redeem window mechanics. Read; do not copy oracle-service ops, Coolify, or unpublished internals. - `code/CL8Y-web`#1 — CL8Y utility-token wording. Different deployable. ## Current codebase No FAQ route; CMM tickers are banned on current-product copy so v0 stubs cannot revive old marketing: - `src/pages/GuidesPage.tsx` — lists only `/guides/open-the-dex`. Copy forbids dumping unpublished marketing manuscripts. - `src/pages/HomePage.tsx` — host chrome today; #9 will become Start Here with purpose lines only (no CR). - `src/pages/MethodologyPage.tsx` — how numbers on this host are sourced; not a token glossary. - `src/pages/ContractsPage.tsx` + `src/data/contracts.ts` — Terra Classic CL8Y CW20, CL8Y/cLUNC pair, BSC CL8Y, MegaETH CL8Y, native `uluna`. No USTR / UST1 / wrap-mapper / treasury addresses. - `src/seo.ts` — closed `DocsPath` union of seven v0 paths. No `/ust1`. - `src/lib/dexHref.ts` — `CAMPAIGNS` closed vocabulary; no `ust1` / `guides-token-treasury`. - `src/App.tsx` — seven `Route` entries; unknown paths 404 via nginx `try_files … =404`. - `src/content/invariants.ts` — `BANNED_CURRENT_COPY` includes `UST1`, `USTR`; `FORBIDDEN_CLAIM_PATTERNS` bans TVL / “best DEX” / CoinGecko / CMC / DeFiLlama. - `e2e/crawl.spec.ts` — currently hardcodes the seven v0 paths (must follow `ROUTES` after this path is added; do not assume loc count 7/8/9 if #9–#12 land first). - `src/verify-dist.test.ts` — follows `ROUTES`; sitemap loc count follows that module. - Architecture §4: no UST1 FAQ row; future UST1 page called out as a later issue. A complete FAQ therefore must add **one** allowlisted path in the same PR (seo union, campaign id, App route, prerender, sitemap, crawl tests, ARCHITECTURE §4, bounded `BANNED_CURRENT_COPY` exception). Do not add `/ustr`, `/ustc`, `/guides/ust1`, `/guides/ustr`, or `/guides/faq` as extra routes — support deep-links are in-page fragment ids on the one manuscript. ### Duplicates / already implemented | Work | Action | | --- | --- | | #1 architecture, #2 review, #5 CI | Unrelated; do not reopen | | #3 v0 stubs | Prerequisite host | | #9 Start Here on `/` | Sibling map; purpose lines only. Different problem. That PR must not register `/ust1`. | | #10 first-use / #11 Bridge / #12 DEX how-to | Sibling how-tos. #12 may mention DEX wrap; it must not teach CMM treasury CR or USTC→USTR windows. | | Unpublished marketing `content/guides/` | Forbidden to dump here (INVARIANTS 14) | | `code/ustr-cmm` Treasury SPA | Cite the live UI for live CR; do not copy the dashboard into this host | | `code/ustr-cmm` `docs/ECONOMICS.md` | Source of design rationale. Do not paste the whitepaper, auction theory, or 5-year pool manuscript onto docs.cl8y.com | | `code/ust1-window` operator / oracle tickets | Different repo; this page is a retail FAQ, not an oracle runbook | If `/ust1` already exists as a complete prerendered FAQ (glossary, windows, backing, cLUNC unwrap/burn, CR no-double-count, sourced addresses only, unique title/canonical) 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 mix up USTC, USTR, and UST1. Today: - `/` will map products (#9) without explaining conversion windows, backing, unwrap, or CR accounting. - `/methodology` only says figures must be first-party; it does not define the assets. - `/contracts` lists CL8Y addresses, not CMM treasury/window/wrap. - Chat answers invite invented “fully backed,” frozen CR%, and “burning cLUNC” as a DEX deflation story. This is documentation copy + one new prerendered route + copy-safety tests. No wallet UI, no treasury dashboard, no Coolify SKU pick. ## Constraints / guardrails 1. **Route.** Add exactly one path: `/ust1` (architecture-reserved). Title seed `Token and treasury FAQ · CL8Y docs` (wordsmith OK; must stay unique vs `/` after #9 and vs #10–#12). Canonical `https://docs.cl8y.com/ust1` (no trailing slash). Amend ARCHITECTURE §4 in the same PR. Do not add `/ustr`, `/ustc`, or extra children. In-page fragments for support paste: `#ustc-vs-ustr-vs-ust1`, `#conversion-windows`, `#backing`, `#clunc-burn`, `#treasury-ratios`. 2. **Reader.** Users and marketers. Short sentences. FAQ headings as questions. Not a whitepaper. Not a Start Here product map (#9). Not a trading tutorial (#10/#12). 3. **This host stays static.** INVARIANTS 19: no wagmi, WalletConnect, LCD keys, or CMM/DEX screens running here. Do not embed live CR. Point at the first-party CMM Treasury UI for live ratios and at `/methodology` for “this host does not freeze protocol statistics.” 4. **Banned-copy exception (bounded).** Allow `UST1`, `USTR`, and `USTC` as factual names on `/ust1` (and tests for that page / copy module). Keep the ban on GameFi lore, “Buy CL8Y” as a CTA, “the future of DeFi”, TVL, “best DEX”, CoinGecko/CMC/DeFiLlama. Do not leak those tickers onto `/methodology` stubs via shared layout. Do not add `/ustr` as a route just because the FAQ names USTR. 5. **Glossary (required distinctions).** Wordsmith OK; do not collapse these into one “UST” story: | Name | What to say (intent) | Source | | --- | --- | --- | | USTC | Terra Classic native (`uusd`). Legacy network asset. Not UST1. Not USTR. | Terra Classic; CMM swap takes USTC in | | USTR | CMM utility/governance CW20 acquired via the time-limited USTC→USTR swap. Equity: no redemption in CR math | `code/ustr-cmm` README; `skills/frontend-ust1-ratios` pin 1 | | UST1 | CMM collateralized CW20 unstablecoin; minted/burned via ust1-window against treasury collateral (vFDUSD path) | `ustr-cmm` README; `code/ust1-window` README | | LUNC / `uluna` | Terra Classic native | ARCHITECTURE §4 | | cLUNC | CW20 wrap of LUNC via CMM wrap-mapper (DEX pair legs may use it; that is not this FAQ’s wrap lesson) | `ustr-cmm` README wrap-mapper / cLUNC row | | cUSTC | CW20 wrap of USTC via wrap-mapper | same | Do not list GameFi / PROTOCASS / Karnyx / TigerHunt. Do not lead with memecoin / Autoscarcity. 6. **Conversion windows (required).** Two different windows. Do not describe a single “conversion window”: - **USTC→USTR swap** (`ustc-swap`): time-limited, time-decaying rate; USTC flows to treasury; USTR is minted to the user. Do not freeze start/end calendar days, remaining days, or 1.5→2.5 rates unless those exact figures are already first-party constants in *this* repo. Prefer: name the mechanism, then “see the live CMM swap UI for the current rate and whether the window is open.” - **UST1 window** (`ust1-window`): deposit vFDUSD → mint UST1 (forward collateral to treasury); withdraw burns UST1 and pulls collateral. Oracle/rate policy exists on that product; this FAQ may say a published rate is used and can pause — it must not document operator poll intervals, heartbeat, or Coolify. If a window is closed on-chain at implement time, say so in past tense from a sourced first-party sentence; do not invent reopen dates. 7. **Backing.** Explain economic role, not slogans: - USTC is not “backed by” CMM; CMM accepts it into treasury via the swap. - USTR is not a redeemable stable; it is not a CR liability (`frontend-ust1-ratios` pin 1). - UST1 is collateralized; circulating/available supply and CR are live Treasury figures, not docs constants. - cLUNC/cUSTC are wrap receipts for native LUNC/USTC, not a second independent reserve that should be added on top of the native already in CR assets. Forbidden: “fully backed 1:1,” “algorithmic stablecoin,” APY, TVL, fabricated collateral-ratio percentages, CoinGecko proof. 8. **Burning cLUNC.** Required honest sentence: redeeming/unwrapping cLUNC **burns the CW20** and returns native LUNC (minus protocol wrap/unwrap fees as implemented by wrap-mapper). That is not: - burning CL8Y, - a DEX trading-fee burn, - destroying native LUNC off-chain, - the UST1 window burn (that burns **UST1**). Distinguish CMM wrap-mapper (cLUNC/cUSTC) from DEX `/wrap` (#12) and from `cmm-native-wrap` (wLUNC/wUSTC in `ust1-window`) in one short “related wraps” note so marketers do not merge them. Do not freeze `fee_bps` / unwrap all-in % unless already a constant in this repo. 9. **Treasury ratios / double counting (required).** Translate `skills/frontend-ust1-ratios` into plain English. Must hold in copy: - CR% = (CR CMM Assets / CR CMM Liabilities) × 100. - Liabilities for CR = available UST1 (as $1 debt) + cUSTC + cLUNC inventories — **not** raw `total_supply` alone, **not** window volume, **not USTR**. - USTR is equity (no redemption) and is omitted from CR liabilities. - No wrap double-count: raw cLUNC/cUSTC are not CR *assets* (native LUNC/USTC already count). Protocol LP wrap legs belong in Total/display NAV, not `crUsd`. - UST1 held by CMM is not a CR asset. - Docs **must not** print a live CR%, color tier (RED/YELLOW/GREEN/BLUE), or USD NAV. Point at the live Treasury page. Incomplete prices on that UI hide ratios — docs should not invent a substitute number. `/methodology` may gain a one-line pointer to this FAQ for CMM figures; do not move the FAQ onto `/methodology`. 10. **Addresses.** Optional small table. Only strings already published first-party in `code/ustr-cmm` README and/or `code/ust1-window` README (USTR, UST1, treasury, wrap-mapper, cLUNC, cUSTC, ustc-swap, ust1-window). If shown, add them to `src/data/contracts.ts` in this PR and render from that module. Do not invent. Do not paste operator/deployer/oracle-operator keys as a user FAQ. Finder links: first-party or already used CMM pattern (`finder.terraclassic.community/columbus-5`); build with `URL`, not string concat. 11. **CTAs.** Optional DEX CTA via `dexHref` with a new closed campaign id (e.g. `ust1`) — default pair remains `uluna` → Terra Classic CL8Y CW20 execute ids, not UST1 tickers as execute ids. CMM Treasury / CMM app href: first-party origin only, `URL` helper, `rel="noopener noreferrer"` if new tab. Do not make “Buy CL8Y” or “Buy UST1” the primary button. Do not deep-link third-party venues. Do not concatenate visitor query. 12. **Guides index.** Link this FAQ from `/guides` (label Token and treasury FAQ). Optional one-line “mechanics FAQ” link from Start Here CMM section belongs in #9’s PR or a tiny follow-up after #9 lands — **this** PR must not rewrite `/` beyond a single optional link if `/` already has CMM copy; if #9 has not landed, do not take over HomePage. 13. **No wallet / mint UI.** No wrap/mint/redeem forms. Describe using the live CMM UI. 14. **Do not** publish ops internals, unpublished marketing manuscripts, oracle poll/silence env, or extra contract addresses. ## Relevant files | Path | Why | | --- | --- | | `src/pages/` (new page) | FAQ manuscript + fragment ids | | `src/pages/GuidesPage.tsx` | Link to `/ust1` | | `src/App.tsx` | Register the route | | `src/seo.ts` | `DocsPath` + `ROUTES` row; unique title/description | | `src/lib/dexHref.ts` | New closed campaign id if this page emits a DEX CTA | | `src/lib/` (small helper OK) | First-party CMM origin URL builder + unit tests (reuse if #9/#10/#11 already added one) | | `src/content/invariants.ts` | Page-scoped UST1/USTR/USTC allow for `/ust1` only | | `src/content/` (new copy module OK) | FAQ strings so unit tests can forbid hype / frozen CR% / “fully backed” | | `src/data/contracts.ts` | Optional CMM addresses copied from published READMEs | | `e2e/crawl.spec.ts` | New path title/canonical; follow `ROUTES` | | `src/verify-dist.test.ts` | Sitemap loc count follows `ROUTES` | | `docs/ARCHITECTURE.md` §4 / §12 | UST1 FAQ row; document ticker-name exception | | `docs/INVARIANTS.md` | Same exception; still no unverified claims | | `code/ustr-cmm` README + `docs/ARCHITECTURE.md` + `skills/frontend-ust1-ratios` | Names, windows, CR pins (read, do not vendor) | | `code/ust1-window` README | UST1 window mint/burn vs vFDUSD (read, do not vendor) | ## Recommended direction 1. Extract FAQ copy into `src/content/tokenTreasuryFaq.ts` (Q/A strings + optional address rows) so unit tests can forbid banned hype, `fully backed`, frozen `CR%` / `APY` / `TVL`, and GameFi lore without rendering React. 2. New page: H1 Token and treasury FAQ; sections matching the five fragment ids; short “see live Treasury” sentence; guides back-link. 3. Register `/ust1` in `seo.ts` `DocsPath` / `ROUTES`, `App.tsx`, prerender list, sitemap rewrite. Campaign `ust1` (or `guides-token-treasury`) added to `CAMPAIGNS` only if a DEX CTA is emitted. 4. Scoped allowlist: `UST1` / `USTR` / `USTC` permitted in the FAQ module / page tests only. 5. If listing addresses, extend `contracts.ts` from published README strings; tests assert the page only emits those constants. 6. Update ARCHITECTURE §4 (this is the approved UST1 page) and INVARIANTS copy-exception. Do not change nginx, Dockerfile, or Woodpecker shape. 7. Do not land `ECONOMICS.md` wholesale. One FAQ page. ## Acceptance criteria - AC1. `GET /ust1` prerendered HTML (no JS) contains FAQ headings that distinguish USTC, USTR, and UST1. - AC2. The same HTML explains two conversion windows (USTC→USTR swap vs UST1 mint/redeem) as distinct, without freezing remaining days or rates unless those exact figures exist as constants in this repo. - AC3. The same HTML states what backs (or does not redeem) each named asset without “fully backed 1:1” / algorithmic-stable slogans. - AC4. The same HTML explains cLUNC unwrap as burning the CW20 to return native LUNC (minus wrap-mapper fees as sourced), and states that this is not a DEX CL8Y burn and not the UST1-window burn. - AC5. The same HTML explains CR assets vs liabilities, that USTR is omitted from CR liabilities, and that wrap inventory is not counted twice as a CR asset; it does **not** print a live CR% or USD NAV. - AC6. Unique `title` (`Token and treasury FAQ · CL8Y docs` or equivalent); canonical `https://docs.cl8y.com/ust1`. Other routes unchanged except `/guides` listing this child. - AC7. `/guides` links to `/ust1` labeled as the token/treasury FAQ. No second new path. - AC8. No TVL / “best DEX” / CoinGecko / CMC / DeFiLlama / fabricated fee tiers / APY. GameFi lore absent. “Buy CL8Y” is not a CTA. - AC9. `UST1` / `USTR` appear as factual names on this page (and its tests); they must not leak onto `/methodology` stub via shared layout. - AC10. Any contract strings on the page match `src/data/contracts.ts` after this PR (CL8Y set and/or published CMM strings added there). No invented addresses. - AC11. `npm test`, `npm run typecheck`, production `npm run build` with required `VITE_*`, dist unique-title tests, Playwright 5 workers stay green. - AC12. Unknown paths still 404; robots/sitemap MIME unchanged; sitemap locs remain this origin only. Given a reader opens the prerendered `/ust1` page When they read the FAQ without executing JavaScript Then they can tell USTC, USTR, and UST1 apart, describe the two conversion windows without invented remaining time, state backing/redemption honestly, explain cLUNC unwrap/burn versus other burns, and explain how CR accounting avoids wrap double counting, with a pointer to live first-party Treasury figures and no frozen unverified CR%/APY/TVL ## Test plan (functional paths) | # | Path | Expect | | --- | --- | --- | | T1 | `dist/ust1/index.html` | FAQ headings present; unique title/canonical | | T2 | Same file, no JS | USTC, USTR, UST1 named as distinct; two windows named | | T3 | Same file | cLUNC unwrap/burn sentence; CR no-double-count / USTR-not-liability sentence; no numeric CR% | | T4 | Fragment ids | `#ustc-vs-ustr-vs-ust1`, `#conversion-windows`, `#backing`, `#clunc-burn`, `#treasury-ratios` exist as element ids | | T5 | `/guides` HTML | Link to `/ust1` | | T6 | DEX CTA if present | `dexHref` execute ids + new campaign; not ticker execute ids | | T7 | CMM Treasury href if present | First-party origin; `URL` construction; safe `rel` if new tab | | T8 | `/methodology`, `/markets`, `/contracts` | Still unique titles; not overwritten with this H1 | | T9 | `GET /ustr`, `GET /ustc`, `GET /guides/faq` | 404 (not shipped) | | T10 | `GET /no-such-page` | 404 | | T11 | Unit: copy module | Forbidden claim patterns fail if someone pastes TVL / “fully backed” / APY / live CR% | | T12 | Playwright 5 workers | New path assertions; previous crawl tests 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 % / CR% / APY on `/ust1` | Fail AC8 / unit grep | | C2 | GameFi / PROTOCASS / Karnyx / TigerHunt | Absent | | C3 | Primary CTA “Buy CL8Y” / “Buy UST1” or third-party venue | Forbidden | | C4 | `javascript:` / `data:` / protocol-relative CMM/DEX href | Never emitted | | C5 | Visitor query concatenated onto CTA | Forbidden | | C6 | New sitemap loc to a foreign host | Forbidden | | C7 | Dump of unpublished marketing guides or `ECONOMICS.md` wholesale | Forbidden | | C8 | USTR/UST1 on `/methodology` stub via shared layout | Fail; exception is `/ust1` copy only | | C9 | Invented contract not in `contracts.ts` | Fail review | | C10 | Wallet/WC/treasury dashboard UI | Fail review | | C11 | Collapsing USTC/USTR/UST1 into one “UST” | Fail AC1 | | C12 | Teaching DEX wrap as CMM wrap-mapper burn | Fail AC4; point #12 for DEX wrap | ## Verification criteria - `npm test` && `npm run typecheck` && production `npm run build` with required `VITE_*`. - `npm run test:dist` (unique titles/canonicals; sitemap loc count = `ROUTES.length`). - Playwright 5 workers: `/ust1` body sniff for glossary + window + unwrap + CR accounting headings; crawl MIME tests unchanged. - Human: open prerendered `/ust1` and confirm a marketer can answer “is USTR the same as UST1?” and “does burning cLUNC delete LUNC or unwrap a CW20?” from the page alone. - `scripts/check-origins.mjs` still fail-closed without HTTPS origins. - No Coolify hostname/SKU work in this PR. ## Out of scope - Extra docs routes (`/ustr`, `/ustc`, `/guides/ust1`), nginx, Dockerfile, Woodpecker shape, or DEX `Sitemap:` pointer. - Wallet connect, swap execution, wrap/mint/redeem UI, pair create. - Publishing unpublished marketing manuscripts or pasting `ECONOMICS.md` / auction / 5-year pool text. - Inventing or freezing live CR%, fee bps, window remaining days, or extra addresses. - Editing `code/ustr-cmm`, `code/ust1-window`, `code/CL8Y-web`, or the DEX SPA (read-only sources). - Implementing #9–#12 manuscripts. - Choosing hypervisor image, SKU, or a new host. ## First-pass model recommendation Recommendation: grok-high Rationale: Public token/treasury copy must be sourced from `code/ustr-cmm` (CR pins, wrap-mapper, USTC→USTR swap) and `code/ust1-window` without inventing backing, rates, or CR%. It needs a new allowlisted route, a bounded `BANNED_CURRENT_COPY` exception for UST1/USTR/USTC, FAQ fragment ids, optional `contracts.ts` CMM addresses, seo/sitemap/crawl updates, and copy-safety tests. That is more than three production files in one helper and is not docs/test-only maintenance of an existing stub. Token/treasury accounting is founder-adjacent (contracts / wallet-adjacent product claims). Uncertain window-open status and which published rates may be printed fail the Composer rubric (known local edit, low ambiguity). Comparable control-plane calibration: a single RCA Markdown (#170) would be Composer; this spans content policy plus prerender routing more like a cross-module change than a test-helper tweak (#164).
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#13
No description provided.