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

docs(maintenance): last-reviewed, ownership, and planned labels #16

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

Summary

Important pages on https://docs.cl8y.com have no last-reviewed date, no visible ownership/reviewer, and no per-page links to supporting technical sources. Copy that describes functionality which is not live has no required planned / under-development label. Agent-written drafts can be mistaken for official technical guidance.

Ship one shared maintenance contract (do not split):

  1. Last-reviewed date in prerendered HTML (explicit ISO in source; never a build timestamp).
  2. Clear ownership / reviewer chrome using a closed role vocabulary (no personal names or emails on the public page).
  3. Per-page supporting-source links (first-party only) where the page describes mechanics.
  4. Explicit planned / under-development labels on any sentence that describes functionality that is not currently live.
  5. Agent drafts may land and may flag gaps; technical mechanics stay unofficial until a designated first-party technical reviewer marks the page official.

v0 (#3) already shipped crawl files, unique titles, and stub routes. Full manuscripts are out of scope there and are owned by sibling tickets (#9–#15). This issue is the chrome + content contract those manuscripts (and the current stubs) must use.

Parent / siblings (do not re-implement)

  • code/cl8y-docs#3 — v0 host + stubs; out of scope: “Full methodology/guide manuscripts (stubs only).” Prerequisite platform.
  • code/cl8y-docs#9–#13 — Start Here / how-to / FAQ manuscripts. Different reader jobs. They must consume this chrome when they add technical copy; do not wait for those tickets to invent per-page metadata.
  • code/cl8y-docs#14 — verified facts and status on a new /facts path (live vs not-claimed-live inventory + dated fact changelog). Different job. Cite it. This issue’s planned labels are page-local chrome, not the facts ledger. When #14 lands, /facts uses this chrome; do not duplicate the seven-section facts manuscript here.
  • code/cl8y-docs#15 — media kit. Out of scope.
  • src/pages/MethodologyPage.tsx / SourcesPage.tsx — host-wide sourcing policy for numbers. Not last-reviewed / owner chrome, and not a substitute for per-page sources on contracts/guides.
  • docs/ARCHITECTURE.md §4 / §12 / INVARIANTS 13–14 — closed route allowlist; no unverified stats; no unpublished marketing content/guides/.
  • PlasticDigits/cl8y-marketing — governance parent, not this deployable. Do not add docs.cl8y.com routes there.

Current codebase

Layout and seo.ts carry path, title, description, and DEX campaign only. No review date, owner, sources list, or draft/official state.

  • src/components/Layout.tsx — nav (Home / Methodology / Markets / Contracts / Guides) + DEX CTA + footer “First-party static documentation…”. No maintenance chrome.
  • src/seo.ts — RouteMeta is { path, title, description, campaign } for the seven v0 DocsPaths.
  • src/pages/HomePage.tsx — host chrome + four hub links. No last-reviewed.
  • src/pages/MethodologyPage.tsx / SourcesPage.tsx — sourcing policy stubs; child link to /methodology/sources. No owner, no ISO date, no planned labels.
  • src/pages/ContractsPage.tsx + src/data/contracts.ts — five first-party strings. Address list is not a reviewed-as-of stamp.
  • src/pages/MarketsPage.tsx / GuidesPage.tsx / OpenTheDexPage.tsx — stubs.
  • src/content/invariants.ts — BANNED_CURRENT_COPY / FORBIDDEN_CLAIM_PATTERNS only.
  • e2e/crawl.spec.ts + src/verify-dist.test.ts — unique titles/canonicals for the seven v0 paths; no last-reviewed / owner sniff.

Do not add a new path. Do not expand the closed allowlist, sitemap loc set, or dexHref campaign vocabulary in this issue.

Duplicates / already implemented

Work Action
#1 architecture, #2 review, #5 CI Unrelated; do not reopen
#3 v0 stubs Prerequisite host; not this chrome
#9–#13 manuscripts Different reader jobs; they consume this chrome
#14 /facts ledger Different page + different changelog (facts, not last-reviewed)
#15 media Unrelated
/methodology/sources Number-sourcing policy; keep; not ownership chrome
CL8Y-web / DEX / marketing.git Different deployables; do not edit

If every shipped HTML path already shows last-reviewed (or an honest not-yet-reviewed stub), owner/reviewer role, first-party sources where mechanics are described, planned labels on non-live functionality, and AGENTS.md already forbids treating agent drafts as official technical guidance, and AC1–AC12 pass, close as implemented — do not duplicate.

Why the new implementation is needed

Readers (newcomers, marketers, support) cannot tell whether a page was reviewed, who is responsible for it, or which first-party source backs a mechanic. Without this:

  • Stale or agent-draft copy looks as official as reviewed copy.
  • Unreleased work is easy to over-claim as shipped (sibling of #14’s live/planned problem, but it applies on every important page, not only /facts).
  • Supporting sources are buried on /methodology/sources instead of next to the mechanic they support.

This is documentation chrome + a content module + agent/reviewer process text. No new host, no new route, no wallet UI, no Coolify SKU pick.

Constraints / guardrails

  1. No new route. Apply chrome on the existing closed DocsPath set. Sitemap loc count, nginx, Dockerfile, and CAMPAIGNS stay unchanged unless a sibling manuscript issue amends them in its PR.

  2. Reader. Human opening prerendered HTML with JavaScript off. Short labeled fields. Not an incident / uptime / operator status page. Not a second facts ledger (#14).

  3. Important vs stub. Every shipped HTML path renders the chrome so manuscripts cannot forget it.

    status When Required fields
    stub Host chrome / placeholder (current v0 copy on /, /markets, /guides, /guides/open-the-dex unless a sibling already replaced them) Owner role; last-reviewed may be omitted and must display “Not yet reviewed”. No fake ISO date.
    important Page describes product, protocol, contract, or how-to mechanics (/methodology, /methodology/sources, /contracts today; / and guide/FAQ/facts paths once siblings land technical copy) ISO lastReviewed; owner role; reviewState; at least one supporting source when the page asserts a mechanic.

    A sibling manuscript that adds technical copy in the same PR must flip that path from stub to important and fill the required fields. This issue does not write those manuscripts.

  4. Last-reviewed. Explicit YYYY-MM-DD strings in source (pageMaintenance.ts or equivalent). Forbidden: Date.now(), new Date(), git-log scrape, Docker/build timestamps, vite define injection of build time. Updating copy that changes a mechanic requires updating the date in the same PR.

  5. Ownership / reviewer. Closed role vocabulary only, displayed as human labels. Suggested ids (wordsmith OK; keep closed):

    Id Display
    docs-maintainer Docs maintainer
    technical-reviewer Technical reviewer

    Do not print personal names, emails, Telegram handles, or chat logs. Do not invent a public “contact this person” CTA.

  6. reviewState. Closed set: draft | official.

    • draft — agent or unreviewed human copy. Visible label: “Draft — not official guidance” (or equivalent) in prerendered HTML.
    • official — a designated first-party technical reviewer has reviewed the technical mechanics on that page. Last-reviewed must be set.

    Agent-written documentation is allowed for drafting and for identifying gaps. Technical mechanics (how products, contracts, bridges, DEX routes, or tokens work) stay draft until that review. Do not treat agent drafts as official. This is process in AGENTS.md + the visible reviewState label; it is not a CAC workflow label and does not apply ready / agent:implement.

  7. Supporting sources. First-party only. Build with URL (not string concat, not window.location, not visitor query). Allowed targets:

    • Paths on this host (/methodology/sources, /contracts, and later /facts only if that route already exists in ROUTES).
    • Public first-party origins already used on this host (https://docs.cl8y.com, https://dex.cl8y.com, https://bridge.cl8y.com, https://cl8y.com, indexer only when VITE_INDEXER_ORIGIN is set and equals https://indexer.dex.cl8y.com).
    • Public Forgejo files in code/cl8y-docs, code/cl8y-dex-terraclassic, code/cl8y-bridge-monorepo, code/CL8Y-web, code/ustr-cmm (https git.cl8y.com blob/tree URLs). No private-repo hrefs.

    rel="noopener noreferrer" if target="_blank". No CoinGecko / CMC / DeFiLlama / CEX / Telegram / Discord as sources. No javascript:, data:, protocol-relative, or ?url= redirectors. Stub pages may link only to /methodology/sources (policy) without pretending a mechanic is sourced.

  8. Planned / under-development. Closed labels: planned | under-development. Any sentence that describes functionality that is not currently live on a first-party public surface must carry one of those labels in prerendered HTML (visible text, not color-only). Do not invent a product roadmap (INVARIANTS 13; #14 constraint 7). Allowed: label copy that is already on the page; point at #14 for the live/planned inventory. Do not list GameFi / PROTOCASS / Karnyx / TigerHunt. Do not mention operator hosts, VMs, Coolify, tokens, or queue ids.

  9. Claims. BANNED_CURRENT_COPY and FORBIDDEN_CLAIM_PATTERNS stay. No fee / TVL / volume / ranking / APY figures. This chrome must not become a place to sneak unverified stats.

  10. CTAs. Unchanged. Still dexHref + closed campaigns. Do not add a campaign for this chrome. Do not make “Buy CL8Y” a button.

  11. No wallet / trading UI. No wagmi, WalletConnect, LCD keys, or DEX screens.

  12. Do not publish ops internals, unpublished marketing manuscripts, extra contract addresses, or personal reviewer identities.

Relevant files

Path Why
src/content/pageMaintenance.ts (new, preferred) Per-path status, ISO lastReviewed, owner role, reviewState, source hrefs; unit tests
src/components/PageMaintenance.tsx (new) Prerendered chrome: date / not-yet-reviewed, owner, draft vs official, sources list
src/components/PlannedLabel.tsx (new, optional) Visible planned / under-development marker for inline use
src/components/Layout.tsx Render maintenance chrome for every DocsPath so pages cannot omit it
src/pages/*.tsx Use planned labels on any non-live sentence; do not rewrite sibling manuscripts
src/seo.ts Unchanged path set; do not add fields that drift prerender/sitemap
AGENTS.md Agent-draft vs official technical review; last-reviewed must move with mechanic edits
docs/ARCHITECTURE.md §4 / §12 Note maintenance chrome on shipped HTML; claims still fail-closed
docs/INVARIANTS.md New invariant: last-reviewed / owner / planned labels / draft≠official
skills/docs-static-host/SKILL.md Point agents at the maintenance module
e2e/crawl.spec.ts Body sniff: chrome present on all seven paths
src/verify-dist.test.ts No-JS sniff for last-reviewed or “Not yet reviewed”; draft label; no javascript: in source hrefs
src/content/invariants.ts Unchanged bans; tests may grep that chrome copy does not violate them

Recommended direction

  1. Put the per-path record in src/content/pageMaintenance.ts keyed by DocsPath. Unit-test: every ROUTES path has a record; important rows have YYYY-MM-DD and reviewState; stub rows have no fake date; source hrefs are https:// first-party or in-site paths; unknown role ids throw.
  2. PageMaintenance renders inside Layout (footer or under H1) so prerender always includes it. data-testid="page-maintenance" for Playwright.
  3. Export a tiny PlannedLabel (or a <span class="docs-planned">) and use it on current stub sentences only if they already imply unreleased work. Do not add a roadmap section.
  4. AGENTS.md: agent PRs may set reviewState: draft; they must not flip official or invent last-reviewed dates. Mechanic-changing PRs update lastReviewed in the same change. Official status is a human/reviewer edit.
  5. Do not change nginx, Dockerfile, Woodpecker shape, MIME rules, or origin checks. Unknown paths still 404.

Acceptance criteria

  • AC1. Every prerendered DocsPath HTML (no JS) contains the maintenance chrome (data-testid="page-maintenance" or equivalent labeled fields).
  • AC2. Stub paths display “Not yet reviewed” (or equivalent) and do not contain a fabricated ISO date. Important paths (/methodology, /methodology/sources, /contracts at filing) contain an explicit YYYY-MM-DD from source.
  • AC3. Chrome shows an owner/reviewer role from the closed vocabulary, not a personal name or email.
  • AC4. Important paths include at least one supporting-source link that is first-party (https:// first-party origin, in-site path, or public git.cl8y.com/code/… URL). No javascript: / data: / protocol-relative / ?url=.
  • AC5. reviewState: draft pages show a visible “not official guidance” (or equivalent) label in prerendered HTML. official is only present when lastReviewed is set.
  • AC6. Any copy on these pages that describes not-yet-live functionality is labeled planned or under-development in the HTML. No invented roadmap table. No GameFi lore.
  • AC7. Titles, canonicals, sitemap loc set, and CAMPAIGNS remain the v0 seven (unless a sibling already merged a new route — then chrome applies to that path too; this PR must not be the one that adds /facts or Start Here copy).
  • AC8. BANNED_CURRENT_COPY / FORBIDDEN_CLAIM_PATTERNS still hold on dist HTML. No TVL / “best DEX” / CoinGecko / CMC / DeFiLlama. “Buy CL8Y” is not a CTA.
  • AC9. AGENTS.md (and the static-host skill) states: agent drafts are allowed; technical mechanics are unofficial until designated first-party technical review; last-reviewed dates are source literals, not build time.
  • AC10. npm test, npm run typecheck, npm run build + dist unique-title tests, Playwright 5 workers stay green.
  • AC11. robots/sitemap MIME, clickjacking headers, and missing-file 404 behavior unchanged.
  • AC12. Architecture / INVARIANTS document the maintenance chrome; they do not add a new public path.

Given a reader opens any shipped docs.cl8y.com page with JavaScript off When they look at the page chrome Then they see last-reviewed or an honest not-yet-reviewed stub, an owner/reviewer role, draft vs official status, and (on important pages) first-party supporting sources, and any not-yet-live functionality on the page is labeled planned or under-development

Test plan (functional paths)

# Path Expect
T1 dist/index.html and each other dist/**/index.html for ROUTES Maintenance chrome present; unique title/canonical unchanged
T2 Same files, no JS Stub paths: “Not yet reviewed”; important paths: ISO date from source
T3 Same files Owner role text from closed vocabulary; no @ email
T4 /methodology, /methodology/sources, /contracts At least one first-party source href
T5 Draft pages Visible not-official label
T6 sitemap.xml Unchanged loc set vs pre-PR (no extra loc from this issue)
T7 Unit: pageMaintenance.ts Every DocsPath has a record; important requires date + reviewState; bad hrefs fail
T8 Playwright 5 workers Chrome sniff on all current routes; crawl MIME tests unchanged
T9 GET /no-such-page Still 404

Test plan (copy safety)

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

# Vector Expect
C1 Build-time / Date.now() last-reviewed Fail AC2 / unit
C2 Personal name or email in chrome Fail AC3
C3 CoinGecko / CMC / DeFiLlama / Telegram as source href Fail AC4
C4 javascript: / data: / // / ?url= source Never emitted
C5 Invented product roadmap in this chrome Fail AC6 / #14 boundary
C6 Unverified TVL/volume/fee % in chrome copy Fail AC8
C7 Dump of unpublished marketing guides Forbidden
C8 Wallet/WC/trading UI Fail review
C9 Operator/host/Coolify/uptime copy Forbidden on this public chrome
C10 Flipping official without last-reviewed Fail unit / AC5
C11 Agent-only PR marking technical mechanics official Fail AC9 / review

Verification criteria

  • npm test && npm run typecheck && production npm run build with required VITE_*.
  • npm run test:dist (unique titles/canonicals unchanged; maintenance chrome greps).
  • Playwright 5 workers: chrome present on every current route; MIME/404 tests unchanged.
  • Human: open prerendered /contracts and /methodology and confirm last-reviewed, role, sources, and draft/official without running JavaScript.
  • scripts/check-origins.mjs still fail-closed without HTTPS origins.
  • No Coolify hostname/SKU work in this PR.

Out of scope

  • New public paths (/facts stays #14; Start Here copy stays #9; guides/FAQ stay #10–#13).
  • Writing the sibling manuscripts.
  • Operator incident/uptime status, Coolify, hosts, VMs, tokens, or queue ids.
  • Wallet connect, swap execution, wrap/mint UI, pair create.
  • Publishing unpublished marketing manuscripts or extra contract addresses.
  • Inventing DEX fee-tier tables, CMM collateral ratios, or a product roadmap.
  • Editing code/CL8Y-web, the Bridge monorepo, the DEX SPA, or PlasticDigits/cl8y-marketing (read-only for names/origins).
  • Choosing hypervisor image, SKU, or a new host.
  • Applying CAC workflow labels (ready, agent:implement, agent:review) from this chrome.

First-pass model recommendation

Recommendation: grok-high

Rationale: This is a site-wide prerender chrome contract, not a one-page copy edit. Expected files span a new pageMaintenance module, PageMaintenance (and optional planned-label) component, Layout.tsx, current page TSX for planned markers, AGENTS.md / ARCHITECTURE.md / INVARIANTS.md, plus dist and Playwright sniffs — more than three production files and a cross-cutting metadata rule every later manuscript must inherit. Composer fails the local three-file / no cross-cutting-contract criteria. Risk is claim-safety and honesty: a fake last-reviewed date, an official stamp on agent-draft mechanics, or an unlabeled unreleased feature becomes canonical public copy. Verify with unit tests on the maintenance module, no-JS dist greps, and Playwright 5 workers. Control-plane calibration: unlike a single RCA document (PR #170) or a test-helper tweak (#164), this is closer to a cross-module chrome change than a one-file docs edit.

## Summary Important pages on `https://docs.cl8y.com` have no last-reviewed date, no visible ownership/reviewer, and no per-page links to supporting technical sources. Copy that describes functionality which is not live has no required planned / under-development label. Agent-written drafts can be mistaken for official technical guidance. Ship one shared maintenance contract (do not split): 1. Last-reviewed date in prerendered HTML (explicit ISO in source; never a build timestamp). 2. Clear ownership / reviewer chrome using a closed role vocabulary (no personal names or emails on the public page). 3. Per-page supporting-source links (first-party only) where the page describes mechanics. 4. Explicit `planned` / `under-development` labels on any sentence that describes functionality that is not currently live. 5. Agent drafts may land and may flag gaps; technical mechanics stay unofficial until a designated first-party technical reviewer marks the page official. v0 (#3) already shipped crawl files, unique titles, and stub routes. Full manuscripts are out of scope there and are owned by sibling tickets (#9–#15). This issue is the chrome + content contract those manuscripts (and the current stubs) must use. ### Parent / siblings (do not re-implement) - `code/cl8y-docs`#3 — v0 host + stubs; out of scope: “Full methodology/guide manuscripts (stubs only).” Prerequisite platform. - `code/cl8y-docs`#9–#13 — Start Here / how-to / FAQ manuscripts. Different reader jobs. They must consume this chrome when they add technical copy; do not wait for those tickets to invent per-page metadata. - `code/cl8y-docs`#14 — verified facts and status on a **new** `/facts` path (live vs not-claimed-live inventory + dated **fact changelog**). Different job. Cite it. This issue’s planned labels are page-local chrome, not the facts ledger. When #14 lands, `/facts` uses this chrome; do not duplicate the seven-section facts manuscript here. - `code/cl8y-docs`#15 — media kit. Out of scope. - `src/pages/MethodologyPage.tsx` / `SourcesPage.tsx` — host-wide sourcing **policy** for numbers. Not last-reviewed / owner chrome, and not a substitute for per-page sources on contracts/guides. - `docs/ARCHITECTURE.md` §4 / §12 / INVARIANTS 13–14 — closed route allowlist; no unverified stats; no unpublished marketing `content/guides/`. - `PlasticDigits/cl8y-marketing` — governance parent, not this deployable. Do not add docs.cl8y.com routes there. ## Current codebase Layout and `seo.ts` carry path, title, description, and DEX campaign only. No review date, owner, sources list, or draft/official state. - `src/components/Layout.tsx` — nav (Home / Methodology / Markets / Contracts / Guides) + DEX CTA + footer “First-party static documentation…”. No maintenance chrome. - `src/seo.ts` — `RouteMeta` is `{ path, title, description, campaign }` for the seven v0 `DocsPath`s. - `src/pages/HomePage.tsx` — host chrome + four hub links. No last-reviewed. - `src/pages/MethodologyPage.tsx` / `SourcesPage.tsx` — sourcing policy stubs; child link to `/methodology/sources`. No owner, no ISO date, no planned labels. - `src/pages/ContractsPage.tsx` + `src/data/contracts.ts` — five first-party strings. Address list is not a reviewed-as-of stamp. - `src/pages/MarketsPage.tsx` / `GuidesPage.tsx` / `OpenTheDexPage.tsx` — stubs. - `src/content/invariants.ts` — `BANNED_CURRENT_COPY` / `FORBIDDEN_CLAIM_PATTERNS` only. - `e2e/crawl.spec.ts` + `src/verify-dist.test.ts` — unique titles/canonicals for the seven v0 paths; no last-reviewed / owner sniff. Do **not** add a new path. Do **not** expand the closed allowlist, sitemap loc set, or `dexHref` campaign vocabulary in this issue. ### Duplicates / already implemented | Work | Action | | --- | --- | | #1 architecture, #2 review, #5 CI | Unrelated; do not reopen | | #3 v0 stubs | Prerequisite host; not this chrome | | #9–#13 manuscripts | Different reader jobs; they consume this chrome | | #14 `/facts` ledger | Different page + different changelog (facts, not last-reviewed) | | #15 media | Unrelated | | `/methodology/sources` | Number-sourcing policy; keep; not ownership chrome | | CL8Y-web / DEX / marketing.git | Different deployables; do not edit | If every shipped HTML path already shows last-reviewed (or an honest not-yet-reviewed stub), owner/reviewer role, first-party sources where mechanics are described, planned labels on non-live functionality, and `AGENTS.md` already forbids treating agent drafts as official technical guidance, and AC1–AC12 pass, close as implemented — do not duplicate. ## Why the new implementation is needed Readers (newcomers, marketers, support) cannot tell whether a page was reviewed, who is responsible for it, or which first-party source backs a mechanic. Without this: - Stale or agent-draft copy looks as official as reviewed copy. - Unreleased work is easy to over-claim as shipped (sibling of #14’s live/planned problem, but it applies on **every** important page, not only `/facts`). - Supporting sources are buried on `/methodology/sources` instead of next to the mechanic they support. This is documentation chrome + a content module + agent/reviewer process text. No new host, no new route, no wallet UI, no Coolify SKU pick. ## Constraints / guardrails 1. No new route. Apply chrome on the existing closed `DocsPath` set. Sitemap loc count, nginx, Dockerfile, and `CAMPAIGNS` stay unchanged unless a sibling manuscript issue amends them in **its** PR. 2. Reader. Human opening prerendered HTML with JavaScript off. Short labeled fields. Not an incident / uptime / operator status page. Not a second facts ledger (#14). 3. Important vs stub. Every shipped HTML path renders the chrome so manuscripts cannot forget it. | `status` | When | Required fields | | --- | --- | --- | | `stub` | Host chrome / placeholder (current v0 copy on `/`, `/markets`, `/guides`, `/guides/open-the-dex` unless a sibling already replaced them) | Owner role; last-reviewed may be omitted and **must** display “Not yet reviewed”. No fake ISO date. | | `important` | Page describes product, protocol, contract, or how-to mechanics (`/methodology`, `/methodology/sources`, `/contracts` today; `/` and guide/FAQ/facts paths once siblings land technical copy) | ISO `lastReviewed`; owner role; `reviewState`; at least one supporting source when the page asserts a mechanic. | A sibling manuscript that adds technical copy in the same PR must flip that path from `stub` to `important` and fill the required fields. This issue does not write those manuscripts. 4. Last-reviewed. Explicit `YYYY-MM-DD` strings in source (`pageMaintenance.ts` or equivalent). **Forbidden:** `Date.now()`, `new Date()`, git-log scrape, Docker/build timestamps, `vite` define injection of build time. Updating copy that changes a mechanic requires updating the date in the **same** PR. 5. Ownership / reviewer. Closed role vocabulary only, displayed as human labels. Suggested ids (wordsmith OK; keep closed): | Id | Display | | --- | --- | | `docs-maintainer` | Docs maintainer | | `technical-reviewer` | Technical reviewer | Do not print personal names, emails, Telegram handles, or chat logs. Do not invent a public “contact this person” CTA. 6. `reviewState`. Closed set: `draft` | `official`. - `draft` — agent or unreviewed human copy. Visible label: “Draft — not official guidance” (or equivalent) in prerendered HTML. - `official` — a designated first-party technical reviewer has reviewed the **technical mechanics** on that page. Last-reviewed must be set. Agent-written documentation is allowed for drafting and for identifying gaps. Technical mechanics (how products, contracts, bridges, DEX routes, or tokens work) stay `draft` until that review. Do not treat agent drafts as official. This is process in `AGENTS.md` + the visible `reviewState` label; it is not a CAC workflow label and does not apply `ready` / `agent:implement`. 7. Supporting sources. First-party only. Build with `URL` (not string concat, not `window.location`, not visitor query). Allowed targets: - Paths on this host (`/methodology/sources`, `/contracts`, and later `/facts` only if that route already exists in `ROUTES`). - Public first-party origins already used on this host (`https://docs.cl8y.com`, `https://dex.cl8y.com`, `https://bridge.cl8y.com`, `https://cl8y.com`, indexer only when `VITE_INDEXER_ORIGIN` is set and equals `https://indexer.dex.cl8y.com`). - Public Forgejo files in `code/cl8y-docs`, `code/cl8y-dex-terraclassic`, `code/cl8y-bridge-monorepo`, `code/CL8Y-web`, `code/ustr-cmm` (https git.cl8y.com blob/tree URLs). No private-repo hrefs. `rel="noopener noreferrer"` if `target="_blank"`. No CoinGecko / CMC / DeFiLlama / CEX / Telegram / Discord as sources. No `javascript:`, `data:`, protocol-relative, or `?url=` redirectors. Stub pages may link only to `/methodology/sources` (policy) without pretending a mechanic is sourced. 8. Planned / under-development. Closed labels: `planned` | `under-development`. Any sentence that describes functionality that is **not currently live** on a first-party public surface must carry one of those labels in prerendered HTML (visible text, not color-only). Do **not** invent a product roadmap (INVARIANTS 13; #14 constraint 7). Allowed: label copy that is already on the page; point at #14 for the live/planned **inventory**. Do not list GameFi / PROTOCASS / Karnyx / TigerHunt. Do not mention operator hosts, VMs, Coolify, tokens, or queue ids. 9. Claims. `BANNED_CURRENT_COPY` and `FORBIDDEN_CLAIM_PATTERNS` stay. No fee / TVL / volume / ranking / APY figures. This chrome must not become a place to sneak unverified stats. 10. CTAs. Unchanged. Still `dexHref` + closed campaigns. Do not add a campaign for this chrome. Do not make “Buy CL8Y” a button. 11. No wallet / trading UI. No wagmi, WalletConnect, LCD keys, or DEX screens. 12. Do not publish ops internals, unpublished marketing manuscripts, extra contract addresses, or personal reviewer identities. ## Relevant files | Path | Why | | --- | --- | | `src/content/pageMaintenance.ts` (new, preferred) | Per-path `status`, ISO `lastReviewed`, owner role, `reviewState`, source hrefs; unit tests | | `src/components/PageMaintenance.tsx` (new) | Prerendered chrome: date / not-yet-reviewed, owner, draft vs official, sources list | | `src/components/PlannedLabel.tsx` (new, optional) | Visible `planned` / `under-development` marker for inline use | | `src/components/Layout.tsx` | Render maintenance chrome for every `DocsPath` so pages cannot omit it | | `src/pages/*.tsx` | Use planned labels on any non-live sentence; do not rewrite sibling manuscripts | | `src/seo.ts` | Unchanged path set; do not add fields that drift prerender/sitemap | | `AGENTS.md` | Agent-draft vs official technical review; last-reviewed must move with mechanic edits | | `docs/ARCHITECTURE.md` §4 / §12 | Note maintenance chrome on shipped HTML; claims still fail-closed | | `docs/INVARIANTS.md` | New invariant: last-reviewed / owner / planned labels / draft≠official | | `skills/docs-static-host/SKILL.md` | Point agents at the maintenance module | | `e2e/crawl.spec.ts` | Body sniff: chrome present on all seven paths | | `src/verify-dist.test.ts` | No-JS sniff for last-reviewed or “Not yet reviewed”; draft label; no `javascript:` in source hrefs | | `src/content/invariants.ts` | Unchanged bans; tests may grep that chrome copy does not violate them | ## Recommended direction 1. Put the per-path record in `src/content/pageMaintenance.ts` keyed by `DocsPath`. Unit-test: every `ROUTES` path has a record; `important` rows have `YYYY-MM-DD` and `reviewState`; `stub` rows have no fake date; source hrefs are `https://` first-party or in-site paths; unknown role ids throw. 2. `PageMaintenance` renders inside `Layout` (footer or under H1) so prerender always includes it. `data-testid="page-maintenance"` for Playwright. 3. Export a tiny `PlannedLabel` (or a `<span class="docs-planned">`) and use it on current stub sentences only if they already imply unreleased work. Do not add a roadmap section. 4. `AGENTS.md`: agent PRs may set `reviewState: draft`; they must not flip `official` or invent last-reviewed dates. Mechanic-changing PRs update `lastReviewed` in the same change. Official status is a human/reviewer edit. 5. Do not change nginx, Dockerfile, Woodpecker shape, MIME rules, or origin checks. Unknown paths still 404. ## Acceptance criteria - AC1. Every prerendered `DocsPath` HTML (no JS) contains the maintenance chrome (`data-testid="page-maintenance"` or equivalent labeled fields). - AC2. Stub paths display “Not yet reviewed” (or equivalent) and do **not** contain a fabricated ISO date. Important paths (`/methodology`, `/methodology/sources`, `/contracts` at filing) contain an explicit `YYYY-MM-DD` from source. - AC3. Chrome shows an owner/reviewer **role** from the closed vocabulary, not a personal name or email. - AC4. Important paths include at least one supporting-source link that is first-party (`https://` first-party origin, in-site path, or public `git.cl8y.com/code/…` URL). No `javascript:` / `data:` / protocol-relative / `?url=`. - AC5. `reviewState: draft` pages show a visible “not official guidance” (or equivalent) label in prerendered HTML. `official` is only present when `lastReviewed` is set. - AC6. Any copy on these pages that describes not-yet-live functionality is labeled `planned` or `under-development` in the HTML. No invented roadmap table. No GameFi lore. - AC7. Titles, canonicals, sitemap loc set, and `CAMPAIGNS` remain the v0 seven (unless a sibling already merged a new route — then chrome applies to that path too; this PR must not be the one that adds `/facts` or Start Here copy). - AC8. `BANNED_CURRENT_COPY` / `FORBIDDEN_CLAIM_PATTERNS` still hold on dist HTML. No TVL / “best DEX” / CoinGecko / CMC / DeFiLlama. “Buy CL8Y” is not a CTA. - AC9. `AGENTS.md` (and the static-host skill) states: agent drafts are allowed; technical mechanics are unofficial until designated first-party technical review; last-reviewed dates are source literals, not build time. - AC10. `npm test`, `npm run typecheck`, `npm run build` + dist unique-title tests, Playwright 5 workers stay green. - AC11. robots/sitemap MIME, clickjacking headers, and missing-file 404 behavior unchanged. - AC12. Architecture / INVARIANTS document the maintenance chrome; they do not add a new public path. Given a reader opens any shipped docs.cl8y.com page with JavaScript off When they look at the page chrome Then they see last-reviewed or an honest not-yet-reviewed stub, an owner/reviewer role, draft vs official status, and (on important pages) first-party supporting sources, and any not-yet-live functionality on the page is labeled planned or under-development ## Test plan (functional paths) | # | Path | Expect | | --- | --- | --- | | T1 | `dist/index.html` and each other `dist/**/index.html` for `ROUTES` | Maintenance chrome present; unique title/canonical unchanged | | T2 | Same files, no JS | Stub paths: “Not yet reviewed”; important paths: ISO date from source | | T3 | Same files | Owner role text from closed vocabulary; no `@` email | | T4 | `/methodology`, `/methodology/sources`, `/contracts` | At least one first-party source href | | T5 | Draft pages | Visible not-official label | | T6 | `sitemap.xml` | Unchanged loc set vs pre-PR (no extra loc from this issue) | | T7 | Unit: `pageMaintenance.ts` | Every `DocsPath` has a record; important requires date + reviewState; bad hrefs fail | | T8 | Playwright 5 workers | Chrome sniff on all current routes; crawl MIME tests unchanged | | T9 | `GET /no-such-page` | Still 404 | ## Test plan (copy safety) Not a DeFi attack suite. Keep host crawl/CTA tests from #3 green. | # | Vector | Expect | | --- | --- | --- | | C1 | Build-time / `Date.now()` last-reviewed | Fail AC2 / unit | | C2 | Personal name or email in chrome | Fail AC3 | | C3 | CoinGecko / CMC / DeFiLlama / Telegram as source href | Fail AC4 | | C4 | `javascript:` / `data:` / `//` / `?url=` source | Never emitted | | C5 | Invented product roadmap in this chrome | Fail AC6 / #14 boundary | | C6 | Unverified TVL/volume/fee % in chrome copy | Fail AC8 | | C7 | Dump of unpublished marketing guides | Forbidden | | C8 | Wallet/WC/trading UI | Fail review | | C9 | Operator/host/Coolify/uptime copy | Forbidden on this public chrome | | C10 | Flipping `official` without last-reviewed | Fail unit / AC5 | | C11 | Agent-only PR marking technical mechanics `official` | Fail AC9 / review | ## Verification criteria - `npm test` && `npm run typecheck` && production `npm run build` with required `VITE_*`. - `npm run test:dist` (unique titles/canonicals unchanged; maintenance chrome greps). - Playwright 5 workers: chrome present on every current route; MIME/404 tests unchanged. - Human: open prerendered `/contracts` and `/methodology` and confirm last-reviewed, role, sources, and draft/official without running JavaScript. - `scripts/check-origins.mjs` still fail-closed without HTTPS origins. - No Coolify hostname/SKU work in this PR. ## Out of scope - New public paths (`/facts` stays #14; Start Here copy stays #9; guides/FAQ stay #10–#13). - Writing the sibling manuscripts. - Operator incident/uptime status, Coolify, hosts, VMs, tokens, or queue ids. - Wallet connect, swap execution, wrap/mint UI, pair create. - Publishing unpublished marketing manuscripts or extra contract addresses. - Inventing DEX fee-tier tables, CMM collateral ratios, or a product roadmap. - Editing `code/CL8Y-web`, the Bridge monorepo, the DEX SPA, or `PlasticDigits/cl8y-marketing` (read-only for names/origins). - Choosing hypervisor image, SKU, or a new host. - Applying CAC workflow labels (`ready`, `agent:implement`, `agent:review`) from this chrome. ## First-pass model recommendation Recommendation: grok-high Rationale: This is a site-wide prerender chrome contract, not a one-page copy edit. Expected files span a new `pageMaintenance` module, `PageMaintenance` (and optional planned-label) component, `Layout.tsx`, current page TSX for planned markers, `AGENTS.md` / `ARCHITECTURE.md` / `INVARIANTS.md`, plus dist and Playwright sniffs — more than three production files and a cross-cutting metadata rule every later manuscript must inherit. Composer fails the local three-file / no cross-cutting-contract criteria. Risk is claim-safety and honesty: a fake last-reviewed date, an `official` stamp on agent-draft mechanics, or an unlabeled unreleased feature becomes canonical public copy. Verify with unit tests on the maintenance module, no-JS dist greps, and Playwright 5 workers. Control-plane calibration: unlike a single RCA document (PR #170) or a test-helper tweak (#164), this is closer to a cross-module chrome change than a one-file docs edit.
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
main
renovate/configure
No results found.
Labels
Clear labels   
agent:implement
Agent implement gate

  
agent:research
Research gate; skip implement admit

  
docs

   
feature
Product feature; do not apply ready until gates pass

  
ready
Ready for agent pickup

  
research
Design/architecture; not implement

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

No due date set.

Dependencies

No dependencies set.

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