Creative Index — Maintenance Guide#

How to keep creative.relayctx.com current as new work ships.

Deploying / branches? This file is about the content of the indexes. For how the site is hosted, built, and shipped — Cloudflare Pages, no build step, main = production — see GUIDE.deploy.md.

Design-system canon (v3.5): token values in brand/relay-tokens-v35.css; direction in briefs/BRIEF.interface-v35.md (v3.5-a, product UI); interactive guide brand/relay-brand-guide.html. briefs/SPEC.design-v35.md is v3.5-b (marketing bold concept) — a separate track.

Index structure — hub + areas#

The root index.html is the hub: one card per area, the specs & docs bridge, and reference pages. It should stay a domain overview — individual pages never get cards on the hub.

Each area (concepts/, marketing/, brand/, email/, mcp/) has its own index.html card index and a curated CHANGELOG.md. All indexes are static, hand-maintained files (no build step; nothing scans the repo to regenerate them). A card goes live when its PR merges to main. Always edit the area index on the same branch as the page so the card travels with it.

Every page lands as a bundle: the file, its card in the area index, its _redirects entry (if a clean URL is involved), and a line in the area CHANGELOG.md — same PR. If the page changes what's canonical, the master MANIFEST.md row updates in the same PR too.

URL conventions#

Clean URL redirects live in _redirects (first match wins — keep new rules above the legacy /web/* splat). When a page becomes canonical, add or retarget its clean rule:

/concepts/[name]    /concepts/[name-version]    302

Never point a clean URL at its own .html. Pages serves clean URLs and 301s /x.html → /x on its own, so a rule like /concepts/foo → /concepts/foo.html fights that and produces ERR_TOO_MANY_REDIRECTS — the page becomes unreachable by either form. Rules target the clean path (/concepts/map → /concepts/map-v35); only cross-directory targets carry .html (/concepts/support-form → /concepts/public/support-form-v1.html). A page that Pages already serves needs no rule at all — the only rule you add is the un-versioned alias. Broke production this way on 2026-08-04 with files-v2; it took v1 down with it.

Convention: 302 for clean-URL-to-current-version rules (they retarget as canon moves), 301 for permanent legacy-path migrations.

Labels — canonical / fresh / archived#

Three explicit statuses, one implicit:

Cards with none of these dim to 45% (explorations, stable references). The per-section archive collapse and the live-page count are automatic — the scripts ship in every index.

When a new page ships#

1. Build the file at a versioned path in its area: concepts/app-v36.html
2. Add a card to the area's index.html in the relevant section — tag it is-fresh if it's the newest/active work, is-canon if it's ratified canon, otherwise is-new
3. Update _redirects to point the clean URL at the new version
4. Update the old card — retag is-archived + is-archived-card, move it to the section's archived tail (or the area's Archive section)
5. Add a changelog line to the area's CHANGELOG.md (newest first)

CI backstop: scripts/check_index_cards.py (the "Content checks" workflow) fails a PR if a page under an area folder isn't linked from anywhere in the repo — a card, an inline cross-link from a sibling page, or a doc mention (MANIFEST.md-style). It's deliberately looser than "must have a grid card" — that's still the convention above, but the CI gate only catches the failure mode that actually happened here: a page landing with zero references at all, unreachable and unfindable. A <!-- index-check ignore: pattern --> comment in an area's index.html exempts a path with a reason, for cases that are legitimately not wired up yet.

Vocabulary backstop: scripts/check_vocab.py (same workflow) fails a PR that introduces a retired term — PIN for Code, Relay Code, RelayContext, relaycontext.com, Little Rocket for the entity. _vocab/_VOCAB.md is the source of truth; the script enforces only the unambiguous subset of its Don't say: lines and self-validates against them, so it cannot drift from the vocabulary silently.

It compares against scripts/vocab-baseline.txt, which records the ~150 pre-existing uses found when the check was introduced — so it only fails on drift you add. Removing baselined uses always passes; run --update-baseline afterwards to lock the win. That file is a burn-down backlog, not an accepted state.

Two escapes, both requiring a reason: a line that names a retired term in order to forbid or map it ("never PIN", PIN → Code) is auto-exempt, and any line can carry a vocab-ok comment. Judgment-call terms (send, pass, thread, memory) are deliberately not enforced — they're retired only in a specific sense, and scanning for them literally would bury the signal.

When a page is superseded#

1. Retag its card is-archived (+ is-archived-card) — never remove cards
2. Retarget the clean URL in _redirects to the new version
3. Don't delete old files — they stay reachable at their versioned URL
4. Note the supersession in the area CHANGELOG.md

Sections and their rules#

Hub: Areas · Specs & Docs · Reference — that's it.

Add a section to an area when a genuine new family of work appears; prefer extending an existing one. A section that's all-archived can collapse into the area's archive tail.

concepts/ — Team & Collaborator Onboarding vs. v3.5-a Direction's onboarding cards: the two are easy to conflate but are a genuinely different family — v3.5-a's "Onboarding Flows" / "Sequential Onboarding" are the product's own new-user activation/onboarding UX; "Team & Collaborator Onboarding" is the internal welcome experience for people joining the company (contractors, hires), built and gated separately in relay-resources. Keep new cards in the section that matches which "onboarding" they mean.

Boundary — creative vs the docs environment#

Two estates, two purposes, zero overlap:

• This site (creative.relayctx.com) is the visual estate — clickable concepts, the brand system, marketing, rendered email, MCP visuals, and the briefs that drive them.
• The MkDocs environment (the documentation repos) is the reading estate — user-facing and internal documentation, runbooks, contracts.

Content lives in exactly one of them. Nothing is mirrored: creative pages are never republished into MkDocs, and docs-repo content is never re-rendered here. This repo's own markdown (briefs, changelogs, manifests) renders on-site in the branded reader — an edge middleware (functions/_middleware.js) wraps any *.md URL in the v3.5 shell (?raw=1 for the plain file), so cards can link local markdown directly. Cross-repo specs still link out to their GitHub / MkDocs home. The two are aware of each other and guide people across: the hub's Specs & Docs section links out where a contract lives in a docs repo, and docs pages link to creative.relayctx.com where a visual reference exists. Rule of thumb when placing something new: if it's looked at, it's creative; if it's read as reference, it's docs.

Three layers, never duplicated:

• Spec files (relay-platform/docs/, briefs/) — contract, rules, params
• Site pages (creative.relayctx.com) — visual reference
• Relay transfers — team handoffs and working context

The spec references the site URL; the page references the spec path.

Vocabulary#

All new copy must use locked vocabulary (V&V Session 0, relay KD8684):

• Code not PIN / Relay Code / relay ID
• receive / received not claim / claimed
• relay (user-facing object), transfer (API-facing)
• Item not contribution

Version lineage & provenance#

Archived pages are moved, never deleted. git mv preserves full file history (git log --follow traces a page back through its pre-rename commits — including across the 2026-07-19 web/ → area restructure), old versions stay reachable via _redirects, and their cards are retagged is-archived (never removed). Per-area lineage tables live in each area's CHANGELOG.md.

When a set is superseded: git mv it to a version-suffixed path (v32/, v34-bold/), add a _redirects entry, retag its card is-archived, and drop a short README.md in the archived folder noting what superseded it and when.

Root-level strays: the root now holds only the hub, shared runtime assets (relay-agent-launcher.js, relay-toolbar.js, activation.css — loaded absolutely by pages in several areas; don't move them without a sweep), and reference pages. Anything else retired goes to _archive/ (the graveyard — git mv + a _redirects entry; convention in _archive/README.md).

Last updated: 2026-07-19 · relay-creative/MAINTENANCE.md