# Brief for Claude Code — sgit.ai design improvements

**From:** Dinis Cruz
**To:** a Claude Code session working on this vault
**Date:** 2026-08-11 · site v0.1.3
**Status:** open — standing brief

## Context

You are inside the vault that *is* the sgit.ai website. This is a vault app: 13 generated
HTML pages, decrypted and rendered in the browser, deployed by `sgit push`. The current
design (light theme, system fonts, teal accent, dark terminal blocks) is a functional
first pass written by an agent without visual rendering. It is honest and consistent,
but it has never been through a design iteration with eyes on it.

Your task: **propose and implement design improvements**, keeping the site's voice
(precise, honest, no hype) and its engineering constraints intact.

## What to improve (in rough priority order)

1. **Visual identity.** The site currently has no logotype, no distinctive graphic
   element beyond the server-sees diagram. Explore: a simple wordmark for `sgit.ai`,
   a favicon-style mark (inline SVG only), and a consistent iconography for the
   feature/use-case cards (small inline SVGs, not emoji — emoji render inconsistently).
2. **Hero.** The landing hero is plain text. Consider a restrained visual — e.g. an
   inline-SVG motif of the encrypt-then-push flow, or subtle background texture —
   without pushing the terminal demo below the fold on a laptop.
3. **Typography rhythm.** Check the serif/sans pairing, heading scale, and vertical
   rhythm across landing vs docs pages. All fonts must remain system-stack (no external
   fonts — the sandbox blocks external hosts, and we ship nothing we don't control).
4. **The server-sees diagram.** It's the signature visual of the whole project. Make it
   memorable: consider drawing it as one inline SVG (padlock, arrow, ciphertext) rather
   than two HTML lists, while keeping it accessible (real text, not paths).
5. **Mobile pass.** The nav wraps on small screens; the terminal tabs and Rosetta-stone
   table need a real phone-width check. Test at 360px.
6. **Accessibility.** Verify contrast ratios on the light palette (especially `--dim`
   text and the terminal caption), focus states on tabs/buttons, and heading order.
7. **Micro-interactions.** The reveal-on-scroll and tab switches are minimal. Small
   touches welcome; nothing that requires a framework or breaks without JS.
8. **Optional: dark-mode support** via `prefers-color-scheme`, keeping the light theme
   as default. Only if it can be done cleanly in the token layer of `assets/site.css`.

## Hard constraints (do not break these)

- **The authoring contract.** No `<link href>`, `<script src>`, or `<img src>`
  referencing vault files — assets load through the SG bridge bootstrap that each page
  carries. No external resources of any kind (fonts, CDNs, analytics). Inline SVG is
  the only graphics format.
- **The build system is the source of truth.** Pages are generated by
  `admin/build/build_pages.py` (shared template + per-page bodies). Edit the generator
  and `assets/site.css` / `assets/site.js` — never hand-edit a generated `*.html`.
- **Validation must pass** before any push: `node admin/build/validate.js`
  (JS parse-check, contract scan, internal-link check). Keep it green.
- **Versioning.** Bump `SITE_VERSION` (v0.1.n → n+1) in the generator and add a row to
  `VERSION_LOG` for every push. Record the previous release's vault commit ID
  (from `sgit history log`) in its row while you're there.
- **Voice and honesty.** Beta status, the limitations page, and the "what the server
  can see" disclosures are features of the site, not bugs. Don't soften them, don't
  add superlatives, don't add "military-grade" anything.
- **Content accuracy.** Command examples must match the shipped CLI (v0.14.x). Example
  vault keys are always full-strength generated keys (24-char passphrase style), never
  short human-friendly tokens.

## Workflow

1. `sgit clone <vault-key>` (or `sgit pull` if already cloned).
2. Make changes in the generator + assets; run the build; run validation.
3. If an sg-playwright service is available, screenshot the live pages and iterate on
   what you see; otherwise state clearly what you could not visually verify.
4. `sgit commit -m "site v0.1.n: <what changed>"` and `sgit push`.
5. Leave a short debrief note in `admin/` describing what you changed and why.

## Deliverable

A pushed release (version bumped, versions page updated) plus your debrief note.
Propose before you sweep: if you want to change the site's structure (new pages,
removed sections) rather than its design, write the proposal into `admin/` first and
stop for human review.