From c067e3e99fba9bba07d528230967599da239736f Mon Sep 17 00:00:00 2001 From: MerlinH Date: Mon, 27 Jul 2026 08:29:38 +0000 Subject: [PATCH] feat(site): add responsive tabbed product guide --- .../operations/release-automation.md | 6 +- site/index.html | 566 +++++++++++++++--- 2 files changed, 487 insertions(+), 85 deletions(-) diff --git a/docs/truthmark/engineering/operations/release-automation.md b/docs/truthmark/engineering/operations/release-automation.md index 1d277aa..d719c1a 100644 --- a/docs/truthmark/engineering/operations/release-automation.md +++ b/docs/truthmark/engineering/operations/release-automation.md @@ -1,7 +1,7 @@ --- status: active truth_kind: engineering-operations -last_reviewed: 2026-06-26 +last_reviewed: 2026-07-26 --- # Release Automation @@ -22,6 +22,10 @@ The npm publish workflow runs from `release/**` tag push events, with manual `wo The GitHub Pages workflow deploys the committed static introduction site from `site/**` after pushes to `main` that change the site or Pages workflow. +The static introduction site replaces the positioned hero illustration with a bounded grid at narrow desktop and tablet widths, then stacks the same content at phone widths. The header brand mark uses an inline SVG checkmark that remains contained within its rounded glyph. + +The introduction site groups its overview, workflow guide, truth model, and adoption content into hash-addressable tab pages. The static page keeps each view in the committed HTML, uses client-side navigation as progressive enhancement, and keeps the selected tab visible inside the horizontally scrollable phone navigation. + CodeQL is handled by GitHub's default setup for this repository. Checked-in advanced CodeQL workflow configuration is intentionally absent while default setup is enabled. diff --git a/site/index.html b/site/index.html index 98edc4f..9180806 100644 --- a/site/index.html +++ b/site/index.html @@ -1,8 +1,9 @@ - + + Truthmark — the branch explains itself @@ -95,6 +96,8 @@ .glyph { position: relative; + display: grid; + place-items: center; width: 38px; height: 38px; border: 1px solid rgba(142,230,107,0.55); @@ -103,32 +106,66 @@ box-shadow: 0 0 30px rgba(142,230,107,0.18); } - .glyph::before, - .glyph::after { - content: ""; - position: absolute; - border-radius: 999px; - background: var(--green); + .glyph-mark { + width: 23px; + height: 23px; + fill: none; + stroke: var(--green); + stroke-width: 2.8; + stroke-linecap: round; + stroke-linejoin: round; + filter: drop-shadow(0 0 6px rgba(142,230,107,0.5)); } - .glyph::before { width: 16px; height: 3px; left: 10px; top: 18px; transform: rotate(42deg); } - .glyph::after { width: 23px; height: 3px; left: 15px; top: 16px; transform: rotate(-48deg); } - - .nav-links { + .page-tabs { display: flex; align-items: center; - gap: 21px; + gap: 4px; + padding: 5px; + border: 1px solid var(--line); + border-radius: 999px; + background: rgba(255,255,255,0.035); color: var(--muted); - font-size: 0.94rem; + font-size: 0.88rem; font-weight: 620; } - .nav-links a { + .page-tab { + min-height: 36px; + display: inline-flex; + align-items: center; + padding: 0 14px; + border-radius: 999px; text-decoration: none; - transition: color 150ms ease; + white-space: nowrap; + transition: color 150ms ease, background 150ms ease, box-shadow 150ms ease; } - .nav-links a:hover { color: var(--text); } + .page-tab:hover { color: var(--text); } + + .page-tab[aria-selected="true"] { + color: #06110a; + background: var(--green); + box-shadow: 0 8px 24px rgba(142,230,107,0.2); + } + + .nav-github { + color: var(--muted); + font-size: 0.88rem; + font-weight: 720; + text-decoration: none; + } + + .nav-github:hover { color: var(--text); } + + .page-view { scroll-margin-top: 88px; } + .js .page-view { display: none; } + .js .page-view.active { display: block; animation: page-enter 220ms ease-out; } + + @keyframes page-enter { + from { opacity: 0; transform: translateY(6px); } + to { opacity: 1; transform: translateY(0); } + } .button { display: inline-flex; @@ -211,6 +248,9 @@ grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 12px; margin-top: 34px; + margin-bottom: 0; + padding: 0; + list-style: none; max-width: 690px; } @@ -350,6 +390,179 @@ letter-spacing: -0.015em; } + .page-intro { + display: grid; + grid-template-columns: 0.8fr 1.2fr; + gap: 42px; + align-items: end; + padding: 76px 0 44px; + } + + .page-intro h1, + .page-intro h2 { + margin: 0; + font-size: clamp(2.7rem, 5.5vw, 5.4rem); + line-height: 0.94; + letter-spacing: -0.072em; + text-wrap: balance; + } + + .page-intro-copy { + max-width: 720px; + padding-bottom: 6px; + } + + .page-intro-copy p { + margin: 14px 0 0; + color: var(--muted); + font-size: 1.16rem; + line-height: 1.62; + } + + .page-note { + display: inline-flex; + align-items: center; + gap: 8px; + color: var(--green); + font-size: 0.78rem; + font-weight: 820; + letter-spacing: 0.08em; + text-transform: uppercase; + } + + .workflow-deck { + display: grid; + grid-template-columns: repeat(12, minmax(0, 1fr)); + gap: 14px; + } + + .workflow-card { + grid-column: span 4; + min-height: 260px; + display: flex; + flex-direction: column; + padding: 22px; + border: 1px solid var(--line); + border-radius: 22px; + background: var(--panel); + } + + .workflow-card:nth-child(4), + .workflow-card:nth-child(5) { grid-column: span 6; } + + .workflow-card .mode { + align-self: flex-start; + margin-bottom: 42px; + padding: 5px 9px; + border: 1px solid var(--line); + border-radius: 999px; + color: var(--dim); + font-size: 0.72rem; + font-weight: 780; + letter-spacing: 0.04em; + text-transform: uppercase; + } + + .workflow-card h3 { + margin: auto 0 9px; + font-size: 1.55rem; + letter-spacing: -0.045em; + } + + .workflow-card p { margin: 0; color: var(--muted); line-height: 1.52; } + .workflow-card code { color: var(--green); font-size: 0.82rem; } + + .workflow-card.sync { + border-color: rgba(142,230,107,0.38); + background: linear-gradient(145deg, rgba(142,230,107,0.11), rgba(255,255,255,0.035)); + } + + .truth-anatomy { + display: grid; + grid-template-columns: repeat(3, minmax(0, 1fr)); + gap: 14px; + margin-top: 18px; + } + + .anatomy-card { + position: relative; + min-height: 230px; + padding: 22px; + border: 1px solid var(--line); + border-radius: 22px; + background: var(--panel); + overflow: hidden; + } + + .anatomy-card::before { + content: attr(data-step); + position: absolute; + right: 18px; + top: 10px; + color: rgba(248,251,242,0.08); + font-size: 4rem; + font-weight: 850; + letter-spacing: -0.08em; + } + + .anatomy-card h3 { position: relative; margin: 54px 0 10px; font-size: 1.45rem; letter-spacing: -0.04em; } + .anatomy-card p { position: relative; margin: 0; color: var(--muted); line-height: 1.55; } + + .start-grid { + display: grid; + grid-template-columns: 1.05fr 0.95fr; + gap: 18px; + margin-top: 18px; + } + + .start-card { + padding: 24px; + border: 1px solid var(--line); + border-radius: 24px; + background: var(--panel); + } + + .start-card h3 { margin: 0 0 10px; font-size: 1.55rem; letter-spacing: -0.045em; } + .start-card p { margin: 0; color: var(--muted); line-height: 1.58; } + .start-list { display: grid; gap: 10px; margin-top: 20px; } + + .start-item { + display: grid; + grid-template-columns: 32px minmax(0, 1fr); + gap: 12px; + padding: 13px; + border: 1px solid rgba(220,236,255,0.11); + border-radius: 14px; + background: rgba(255,255,255,0.028); + } + + .start-item b { + width: 30px; + height: 30px; + display: grid; + place-items: center; + border-radius: 10px; + color: #07131f; + background: var(--green); + } + + .start-item strong { display: block; margin-bottom: 4px; } + .start-item span { color: var(--dim); font-size: 0.9rem; line-height: 1.42; } + + .host-cloud { display: flex; flex-wrap: wrap; gap: 8px; margin: 20px 0 0; padding: 0; list-style: none; } + .host-chip { padding: 7px 10px; border: 1px solid var(--line); border-radius: 999px; color: var(--muted); font-size: 0.82rem; } + + .boundary-card { + margin-top: 18px; + padding: 22px; + border: 1px solid rgba(119,217,255,0.25); + border-radius: 22px; + background: linear-gradient(135deg, rgba(119,217,255,0.09), rgba(255,255,255,0.03)); + } + + .boundary-card strong { display: block; margin-bottom: 8px; font-size: 1.1rem; } + .boundary-card p { margin: 0; color: var(--muted); line-height: 1.55; } + .map-grid { display: grid; grid-template-columns: repeat(4, minmax(0, 1fr)); @@ -655,13 +868,72 @@ .timeline, .panel-grid, .split-view, - .install { grid-template-columns: 1fr; } - .stage { min-height: 620px; } + .install, + .page-intro, + .start-grid { grid-template-columns: 1fr; } + + .page-intro { gap: 20px; } + .workflow-card { grid-column: span 6; } + .workflow-card:nth-child(5) { grid-column: span 12; } + + .stage { + display: grid; + grid-template-columns: repeat(2, minmax(0, 1fr)); + gap: 12px; + min-height: auto; + padding: 14px; + } + + .stage::before, + .rail { display: none; } + + .orbit { + position: relative; + inset: auto; + transform: none; + width: 100%; + box-shadow: 0 14px 34px rgba(0,0,0,0.2); + } + + .orbit.core { + grid-column: 1 / -1; + left: auto; + top: auto; + order: -1; + transform: none; + width: 100%; + } + + .node.a, + .node.b, + .node.c, + .node.d { + top: auto; + right: auto; + bottom: auto; + left: auto; + } + .map-grid { grid-template-columns: repeat(2, minmax(0, 1fr)); } .diagram-grid { grid-template-columns: 1fr; } .arrow { transform: rotate(90deg); } .evidence { border-right: 0; border-bottom: 1px solid var(--line); } - .nav-links { display: none; } + + .nav-inner { + flex-wrap: wrap; + gap: 8px 14px; + padding: 10px 0 8px; + } + + .page-tabs { + order: 3; + width: 100%; + overflow-x: auto; + border-radius: 16px; + scrollbar-width: none; + } + + .page-tabs::-webkit-scrollbar { display: none; } } @media (max-width: 680px) { @@ -678,8 +950,10 @@ .nav-inner { min-height: 62px; } .brand { gap: 10px; font-size: 0.98rem; } .glyph { width: 32px; height: 32px; border-radius: 11px; } - .glyph::before { left: 8px; top: 15px; } - .glyph::after { left: 12px; top: 14px; } + .glyph-mark { width: 19px; height: 19px; } + + .page-tab { min-height: 40px; padding: 0 13px; } + .nav-github { font-size: 0.82rem; } .hero { min-height: auto; @@ -719,35 +993,39 @@ .signals, .map-grid, - .split-view { grid-template-columns: 1fr; } + .split-view, + .truth-anatomy { grid-template-columns: 1fr; } + + .page-intro { padding: 44px 0 24px; } + .page-intro h1, + .page-intro h2 { font-size: clamp(2.45rem, 12vw, 3.4rem); } + .page-intro-copy p { font-size: 1rem; line-height: 1.55; } + + .workflow-card, + .workflow-card:nth-child(4), + .workflow-card:nth-child(5) { + grid-column: span 12; + min-height: 220px; + padding: 18px; + border-radius: 18px; + } + + .workflow-card .mode { margin-bottom: 30px; } + .anatomy-card { min-height: 190px; padding: 18px; border-radius: 18px; } + .anatomy-card h3 { margin-top: 42px; } + .start-card { padding: 18px; border-radius: 18px; } + .boundary-card { padding: 18px; border-radius: 18px; } .signals { margin-top: 24px; gap: 10px; } .signal { padding: 13px; border-radius: 14px; } .stage { - display: grid; - gap: 12px; - min-height: auto; + grid-template-columns: 1fr; padding: 14px; border-radius: 24px; } - .stage::before, - .rail { display: none; } - - .orbit { - position: relative; - inset: auto; - transform: none; - width: 100%; - box-shadow: 0 14px 34px rgba(0,0,0,0.2); - } - .orbit.core { - left: auto; - top: auto; - order: -1; - width: 100%; padding: 18px; border-radius: 20px; } @@ -761,16 +1039,6 @@ border-radius: 16px; } - .node.a, - .node.b, - .node.c, - .node.d { - top: auto; - right: auto; - bottom: auto; - left: auto; - } - .route-line { grid-template-columns: 12px minmax(0, 1fr); gap: 8px; @@ -877,20 +1145,23 @@
- + Truthmark -
+
Repository truth carried by the branch
@@ -898,14 +1169,14 @@

Truthmark gives AI-assisted work a reviewable truth layer: current claims, ownership routes, product promises, and implementation facts travel with the same Git branch as the code.

View on GitHub - Open the demo -
-
-
Checkout-nativeAfter setup, normal agent work can proceed from committed repository files.
-
Claim-level reviewDocs change as small, source-backed claims instead of anonymous summaries.
-
Topology awareWhen truth gets too broad, ownership gets repaired rather than hidden.
-
Host-shapedInstructions meet agents in their existing coding environments.
+ Explore the workflows
+
    +
  • Checkout-nativeAfter setup, normal agent work can proceed from committed repository files.
    • +
  • Claim-level reviewDocs change as small, source-backed claims instead of anonymous summaries.
    • +
  • Topology awareWhen truth gets too broad, ownership gets repaired rather than hidden.
    • +
  • Host-shapedInstructions meet agents in their existing coding environments.
    • +
+ + +
+
+
Workflow field guide

Five workflows. One reviewable loop.

+

Truthmark does not turn every activity into a command. Three workflows are clear user entry points; Sync closes functional code changes; Structure appears only when ownership needs repair.

+
+ +
+
+
You start · truth writes/truthmark-document

Document what already exists

Read implementation and tests, then create or update bounded truth docs without changing functional code.

+
You start · code writes/truthmark-realize

Turn accepted truth into code

Use product truth as requirements and engineering truth as implementation context. The source docs remain unchanged.

+
You start · read only/truthmark-check

Audit before review

Inspect routing, evidence, lane shape, and truth health without authorizing writes.

+
Agent finish-time · truth writesTruth Sync

Close the branch honestly

After functional code changes, review mapped truth, capture supported decisions, and update or explicitly leave claims unchanged with evidence.

+
Only when needed · topologyTruth Structure

Repair ownership before adding prose

Split broad routes and overgrown docs when the repository can no longer identify a bounded owner.

+
+
@@ -948,10 +1236,10 @@
- - - - + + + +
@@ -987,6 +1275,13 @@
+
+ +
+
+
Repository truth model

Keep the promise and the mechanism in different rooms.

+

Truthmark links what users can rely on to how the repository currently realizes it. The relationship is explicit, but neither document inherits authority from the other.

+

Two lanes, linked on purpose.

Truthmark can let product and engineering documents reference each other without forcing them into the same voice or authority level.

@@ -996,10 +1291,19 @@
-
+
+

Three committed layers make the handoff legible.

The route map decides ownership, truth docs preserve current claims, and host-native guidance tells the coding agent when each surface may change.

+
+
Route

Find the bounded owner

Changed paths map to an area and its canonical product or engineering truth docs.

+
Truth

Preserve the claim

Human-facing Markdown records current behavior, rationale, boundaries, and evidence in the right lane.

+
Guidance

Meet the agent in its host

Committed skills, prompts, commands, and instruction blocks carry write boundaries into normal coding work.

+
+
+ +

The workflow is deliberately boring at runtime.

Truthmark's ambition is in the repository model, not in requiring every contributor to adopt a new always-on system.

-
+
+ + +
+
+
Adoption path

Install the contract, then get out of the way.

+

Choose the agent host your team already uses. Truthmark commits its guidance, routes, and truth docs to the repository, so the next branch can continue without a background service.

+

Start with the repo, not a server.

Install once, commit the workflow surface, and let future branches carry their truth updates through normal review.

- 
$ cd /path/to/your-repo
+      
$ cd /path/to/your-repo
 $ npm install -g truthmark
 $ truthmark config
+# Add the host you use to .truthmark/config.yml, for example: platforms: [codex]
 $ truthmark init
 $ truthmark check
 
-# After setup, agent guidance and truth routes live in the checkout.
+# After setup, agent guidance and truth routes live in the checkout.
+ +
+
+
+ What lands in the repo +

A small contract with visible parts

+

Every durable surface can be reviewed, blamed, reverted, and carried by the branch.

+
+
1
Config and routesChoose platforms and map code areas to bounded truth owners.
+
2
Human-facing truthKeep product capabilities and engineering reality separate but linked.
+
3
Host-native guidanceInstall the workflow shape where your coding agent already looks.
+
+
+
+ Choose your first move +

Begin with one bounded area

+

Document one implemented behavior with code and test evidence. Then keep coding normally and let finish-time Sync review future changes.

+
    +
  • Codex
  • Claude Code
  • GitHub Copilot
  • OpenCode
  • Antigravity
  • Cursor
    • +
+
Read the quick startOpen the user guide
+
+
+
Presentation is not authority.

This website explains the product. Canonical behavior remains in the repository's README, routed truth docs, source, tests, and configuration. Truthmark adds no required daemon, database, hosted service, or hidden memory layer.

+
+