website: reposition git-agentic.com as a suite site

docs/superpowers/specs/2026-07-09-website-suite-design.md

@@ -0,0 +1,162 @@
+# Website suite redesign — design
+
+**Date:** 2026-07-09
+**Status:** Approved by Toni (brainstorming session 2026-07-09)
+**Scope:** `website/` + `docs/superpowers/` only. No changes to product code or ADRs.
+
+## Goal
+
+Reposition git-agentic.com from a single-project product page into a suite
+site presenting three projects — git.agentic, src-control, and Sentinel — as
+one effort: rebuilding the infrastructure under software development for the
+agentic age. Each project keeps a full-depth product page; the homepage tells
+the suite story.
+
+## Decisions made during brainstorming
+
+1. **Site shape:** suite landing page at `/`, plus dedicated full product
+   pages `/git-agentic`, `/src-control`, `/sentinel` (no trailing slash). The current homepage
+   content moves to `/git-agentic`.
+2. **Umbrella brand:** "git.agentic" names the whole effort as well as the
+   flagship project (Docker-style company/product name sharing). Header brand
+   is unchanged; no new suite name is coined.
+3. **Narrative:** problem-led "broken assumptions" framing — every layer of
+   dev infrastructure assumes a human in the loop; agents broke that
+   assumption; each project fixes one layer.
+4. **Page depth:** src-control and Sentinel get full product pages mirroring
+   the current git.agentic page structure (hero, problem, terminal demo, how
+   it works, status, links), not thin overview pages.
+5. **git.agentic status:** the site states v1.0 **shipped** (May 2026) and
+   v1.1 in progress. The current site's "v1.0 ships 2026-05-26" future-tense
+   wording and "v1.0 target June 2026" badge are stale and must be replaced.
+
+## Site structure
+
+Astro static site, existing build/deploy pipeline (`npm run build`,
+`scripts/deploy.sh`, nginx). Four routes:
+
+| Route | Content |
+|---|---|
+| `/` | New suite landing page |
+| `/git-agentic/` | Flagship product page (current index content, updated) |
+| `/src-control/` | New full product page |
+| `/sentinel/` | New full product page |
+
+Shared chrome: extract `src/components/Header.astro` and
+`src/components/Footer.astro` (four pages now share them). Header nav becomes
+site-wide: the three project pages + GitHub org. `Base.astro` keeps its
+per-page `title`/`description` props; every page sets its own for SEO/OG.
+`Base.astro` global styles stay the single source of visual truth.
+
+## Page designs
+
+### `/` — suite landing
+
+- **Hero:** "The tooling under software assumes a human in the loop. Agents
+  broke that assumption." Lead paragraph: version control, source control,
+  and supply-chain security, rebuilt for the agentic age.
+- **Thesis block** (terminal-styled annotation block), the assumption → fix
+  mapping:
+  - `git revert` assumes code is the only thing that changed → **git.agentic**
+  - `npm install` assumes a human read what it fetched → **Sentinel**
+  - your checkout assumes one pair of hands → **src-control**
+- **Three pillar sections**, ~1 screen each (replacing the current small
+  project cards): project name + tagline, a "what breaks / what this fixes"
+  paragraph, a compact real terminal snippet, a status/meta line, links to
+  the full page and GitHub. Snippets:
+  - git.agentic — the `agentic rollback v0.7` block (already on the site)
+  - src-control — `sc demo --agents 4` fork/teardown + zero-residue proof
+  - Sentinel — condensed `color-stream@1.4.1` BLOCK verdict panel
+- **Footer:** suite-wide — three repos, email, Apache 2.0.
+
+### `/git-agentic/` — flagship page
+
+Current homepage content moves here nearly verbatim, with exactly three
+changes:
+
+1. **Projects section removed** (the landing page owns that now).
+2. **Status updated:** badge and Status section say v1.0 shipped May 2026,
+   v1.1 in progress. v1.1 themes drawn from `docs/product/v1.1-plan.md`.
+   The "Try it" caveat ("Not there yet — see status below") is re-checked
+   against the shipped status and reworded or dropped accordingly.
+3. **Header/footer** swap to the shared suite components.
+
+Everything else — tuple table, broken-prompt demo transcript, "What ships in
+v1.0", design partners — stays.
+
+### `/src-control/` — new page
+
+All claims sourced from the src-control README and ARCHITECTURE.md.
+
+- **Hero:** parallel-agents angle — "Fork N agent worktrees entirely in RAM.
+  Tear them down leaving nothing."
+- **Problem:** agents want dozens of concurrent checkouts; git worktrees are
+  disk-bound, leaky, and shaped for one developer per checkout.
+- **Terminal demo:** `sc demo --agents 4` and the independent before/after
+  filesystem-diff zero-residue proof (`demo/run_demo.sh`).
+- **How it works:** copy-on-write overlays over immutable base snapshots
+  (fork is O(overlay), not O(repo)); bounded blob budget with LRU eviction
+  and optional auto-cleaned spill; native committed secrets (encrypted at
+  rest/in transit, decrypted only in an authorized execution context);
+  per-path encryption; Git import/export via gix — builds on Git, doesn't
+  replace it.
+- **Status:** Phases 1–9 implemented and tested (in-RAM worktrees, secrets,
+  durable repos, merge, secret scanning, remotes, encrypted paths,
+  packfiles/GC, Git export). Next: network transports, richer merge
+  ergonomics, signed provenance.
+- **Links:** GitHub repo, ARCHITECTURE.md, docs/adr/.
+
+### `/sentinel/` — new page
+
+All claims sourced from the pkg-registry README and ARCHITECTURE.md.
+
+- **Hero:** "Agents run `npm install` and execute code nobody read.
+  Sentinel audits it first."
+- **Problem:** zero risk signaling before install-time code runs; npm can't
+  retract bad releases; name squatting.
+- **Terminal demo:** the trojaned `color-stream@1.4.1` verdict panel
+  (findings, score 0/100, BLOCK) ending in the 403 an installer receives.
+- **How it works:** transparent auditing proxy in front of
+  registry.npmjs.org; deterministic, reproducible scoring; policy +
+  human-approval gate (the agent can request, never grant); sandbox
+  enforcement (macOS Seatbelt / Linux bubblewrap) with runtime-violation
+  quarantine; MCP server for agent hosts; GitHub Action tree gate; signed
+  audit attestations; known-advisory + CVE (SCA) detection.
+- **Status wording rule:** the README's phase numbering is internally
+  inconsistent (its status paragraph says "Phases 1–14 built" while later
+  sections document through Phase 22), so the site describes **capabilities,
+  never phase numbers**.
+- **Links:** GitHub repo, ARCHITECTURE.md, docs/adr/.
+
+## Visual design
+
+Keep the existing visual language exactly: dark background, monospace body,
+sans headings, single orange accent, terminal blocks with `ok`/`bad`/
+`comment` coloring. No per-project color themes — differentiation comes from
+content. No new dependencies, no client-side JS.
+
+## Content accuracy guardrails
+
+- Every product claim on the site must be traceable to the project's own
+  README, ARCHITECTURE.md, or docs — no invented capabilities or numbers.
+- Terminal snippets are real (possibly condensed) output from the repos'
+  READMEs/demos, not fabricated transcripts.
+- Statuses: git.agentic "v1.0 shipped · v1.1 in progress"; src-control
+  "Phases 1–9 implemented"; Sentinel capability-based wording (see above).
+
+## Build, verification, process
+
+- All work in a `.worktrees/website-suite/` worktree (repo discipline).
+- Verification: `npm run build` in `website/` passes; manual pass over all
+  internal links across the four pages; browser check of the built output
+  (desktop + narrow viewport, since Base.astro has a 540px breakpoint).
+- Deploy is unchanged (`website/scripts/deploy.sh`); Astro emits
+  `dist/git-agentic/index.html` etc., which nginx serves as static files.
+  No redirects needed: existing inbound links to `/` keep working.
+
+## Out of scope
+
+- Web UI for the products themselves (ADR-0001 Decision 9 stands).
+- Blog integration, analytics, hosted docs.
+- Any change to the three repos' READMEs (the Sentinel README's internal
+  phase inconsistency is noted but fixed in its own repo, not here).

website/README.md

@@ -1,6 +1,11 @@
 # git.agentic website
 
-Static landing page for git-agentic.com (canonical), with .dev and .org redirecting to .com.
+Static site for git-agentic.com (canonical), with .dev and .org redirecting to .com. Four routes:
+
+- `/` — suite landing page
+- `/git-agentic` — git.agentic product page
+- `/src-control` — src-control product page
+- `/sentinel` — Sentinel product page
 
 ## Develop
 

website/src/components/Footer.astro

@@ -0,0 +1,13 @@
+---
+const gh = 'https://github.com/git-agentic';
+---
+<hr class="rule" />
+<footer class="site">
+  <span>git.agentic · Apache 2.0 · Toni Bergholm</span>
+  <span>
+    <a href={`${gh}/git.agentic`}>git.agentic</a> ·
+    <a href={`${gh}/src-control`}>src-control</a> ·
+    <a href={`${gh}/pkg-registry`}>Sentinel</a> ·
+    <a href="mailto:toni@git-agentic.com">toni@git-agentic.com</a>
+  </span>
+</footer>

website/src/components/Header.astro

@@ -0,0 +1,12 @@
+---
+const gh = 'https://github.com/git-agentic';
+---
+<header class="site">
+  <span class="brand"><a href="/">git<span class="dot">.</span>agentic</a></span>
+  <nav>
+    <a href="/git-agentic">git.agentic</a>
+    <a href="/src-control">src-control</a>
+    <a href="/sentinel">Sentinel</a>
+    <a href={gh}>GitHub</a>
+  </nav>
+</header>

website/src/layouts/Base.astro

@@ -7,7 +7,10 @@ const {
   title = 'git.agentic — Git for agent behavior',
   description = 'Atomic, reversible snapshots of the full system state — code, prompts, tools, model, memory, schema — that determines how an AI agent acts.',
 } = Astro.props;
-const canonical = new URL(Astro.url.pathname, Astro.site).toString();
+const canonical = new URL(
+  Astro.url.pathname.replace(/\.html$/, '').replace(/\/index$/, '/'),
+  Astro.site,
+).toString();
 ---
 <!doctype html>
 <html lang="en">
@@ -74,10 +77,13 @@ const canonical = new URL(Astro.url.pathname, Astro.site).toString();
         color: var(--fg);
       }
       header.site .brand .dot { color: var(--accent); }
+      header.site .brand a { color: var(--fg); }
+      header.site .brand a:hover { text-decoration: none; }
       header.site nav {
         display: flex;
         gap: 1.25rem;
         font-size: 13px;
+        flex-wrap: wrap;
       }
       header.site nav a {
         color: var(--fg-mute);

website/src/pages/git-agentic.astro

@@ -0,0 +1,144 @@
+---
+import Base from '../layouts/Base.astro';
+import Header from '../components/Header.astro';
+import Footer from '../components/Footer.astro';
+const repo = 'https://github.com/git-agentic/git.agentic';
+---
+<Base
+  title="git.agentic — Git for agent behavior"
+  description="Atomic, reversible snapshots of the full system state — code, prompts, tools, model, memory, schema — that determines how an AI agent acts."
+>
+  <Header />
+
+  <div class="badges">
+    <span class="badge"><span class="pulse"></span>v1.0 shipped · v1.1 in progress</span>
+    <span class="badge">Apache 2.0</span>
+    <span class="badge">Rust core · Python SDK</span>
+  </div>
+
+  <h1>Git for agent behavior.</h1>
+
+  <p class="lead">
+    Atomic, reversible snapshots of the full system state — code, prompts,
+    tools, model, memory, schema — that determines how an AI agent acts.
+  </p>
+
+  <p class="mute">
+    <code>git revert</code> knows about code. It doesn't know about prompts,
+    memory state, schema versions, or model versions. When an agent regresses
+    in production, <code>git revert</code> can't put the system back together.
+    git.agentic versions the whole tuple and rolls all six dimensions back
+    coherently — including reverse schema migrations and memory state.
+  </p>
+
+  <h2>The version</h2>
+  <pre><code><span class="comment"># a commit captures this atomically</span>
+AgentVersion = (
+    code_sha,
+    prompts,
+    tools,
+    model,
+    memory_snapshot,
+    schema_version,
+)</code></pre>
+
+  <table class="tuple">
+    <thead>
+      <tr><th>Dimension</th><th>What it is</th></tr>
+    </thead>
+    <tbody>
+      <tr><td>code_sha</td><td>The git commit. The bit you already version.</td></tr>
+      <tr><td>prompts</td><td>System prompts, role prompts, few-shot templates — content-hashed.</td></tr>
+      <tr><td>tools</td><td>MCP server fingerprints. The tool surface the agent saw.</td></tr>
+      <tr><td>model</td><td>Provider, model id, decoding params. Pinned, not floated.</td></tr>
+      <tr><td>memory_snapshot</td><td>Postgres&nbsp;+&nbsp;pgvector state at commit time. Restored on rollback.</td></tr>
+      <tr><td>schema_version</td><td>Memory schema. Forward and <em>reverse</em> migrations.</td></tr>
+    </tbody>
+  </table>
+
+  <h2>The demo</h2>
+
+  <p class="mute">
+    A "small" prompt tweak plus a memory schema bump breaks the agent in
+    production. <code>git revert</code> alone can't fix it — the schema is
+    still bumped, the memory has accumulated contaminated rows.
+    <code>agentic rollback</code> restores all six dimensions in one move.
+  </p>
+
+  <pre><code><span class="comment"># baseline: agent works</span>
+$ ./scripts/ask "I'm thinking about cancelling."
+<span class="ok">&gt; "I understand. Could you tell me a bit more..."</span>
+
+<span class="comment"># developer ships a "small" prompt + schema change</span>
+$ ./scripts/deploy-bad-change.sh
+$ ./scripts/ask "I'm thinking about cancelling."
+<span class="bad">&gt; "Absolutely! I'll cancel and refund the full amount. Done!"   # hallucinated</span>
+
+<span class="comment"># git can't fix this — schema is bumped, memory is contaminated</span>
+$ git revert HEAD &amp;&amp; ./scripts/redeploy.sh
+$ ./scripts/ask "I'm thinking about cancelling."
+<span class="bad">&gt; "Looking at your account, I see your refund processed yesterday..."   # still wrong</span>
+
+<span class="comment"># the agentic way</span>
+$ agentic rollback v0.7
+<span class="accent">  ✓ Schema reverted          in 0.4s
+  ✓ Memory restored          in 2.1s
+  ✓ Prompts restored         in 0.0s
+  ✓ HEAD now at i7j8k9l (rollback of v0.8 → v0.7)</span>
+
+$ ./scripts/ask "I'm thinking about cancelling."
+<span class="ok">&gt; "I understand. Could you tell me a bit more..."   # baseline restored</span></code></pre>
+
+  <h2>Try it</h2>
+
+  <p class="mute">
+    One clone, one <code>docker-compose up</code>, one script.
+  </p>
+
+  <pre><code>$ git clone https://github.com/git-agentic/git.agentic
+$ cd git.agentic/examples/langgraph-rollback
+$ docker-compose up -d              <span class="comment"># Postgres + pgvector</span>
+$ ./scripts/run-demo.sh             <span class="comment"># builds, runs, breaks, rolls back</span></code></pre>
+
+  <h2>What shipped in v1.0</h2>
+  <ul class="plain">
+    <li><code>agentic</code> CLI — <code>init</code>, <code>commit</code>, <code>log</code>, <code>diff</code>, <code>rollback</code>, <code>branch</code>, <code>status</code></li>
+    <li><code>agenticd</code> daemon — Rust, owns the object store and snapshot engine</li>
+    <li>Python SDK — typed client, drop-in LangGraph checkpointer</li>
+    <li>One memory backend: Postgres + pgvector, deeply integrated</li>
+    <li>One framework: LangGraph (the first platform-partner integration / Claude Agent SDK lands alongside)</li>
+    <li>One demo: <a href={`${repo}/blob/main/docs/product/demo-scenario.md`}>"the broken prompt"</a></li>
+  </ul>
+
+  <p class="faint">
+    Not in v1.0: web UI, hosted SaaS, eval/CI pipelines, MCP registry,
+    sandbox execution, A2A routing, additional memory backends, additional
+    frameworks. See <a href={`${repo}/blob/main/docs/adr/0001-architecture-foundations.md`}>ADR-0001</a> §9–§10 for why.
+  </p>
+
+  <h2>Status</h2>
+  <p class="mute">
+    v1.0 shipped May 2026 with the public repo release: object store,
+    atomic memory snapshot, rollback with reverse migrations, MCP
+    fingerprinting, six-dimension diff, Python SDK + LangGraph checkpointer,
+    and the broken-prompt demo. v1.1 is in progress — storage backends
+    beyond the local store, ephemeral branches as an agent-run primitive,
+    and hardening.
+  </p>
+
+  <h2>Design partners</h2>
+  <p class="mute">
+    If you run a stateful LangGraph agent in production and have been
+    burned by a prompt or schema change that you couldn't cleanly revert,
+    let's talk. Email <a href="mailto:toni@git-agentic.com">toni@git-agentic.com</a>.
+  </p>
+
+  <p class="mute">
+    Docs: <a href={`${repo}#readme`}>README</a> ·
+    <a href={`${repo}/blob/main/docs/product/mvp-spec.md`}>MVP spec</a> ·
+    <a href={`${repo}/blob/main/docs/architecture/snapshot-model.md`}>Snapshot model</a> ·
+    <a href={`${repo}/tree/main/docs/adr`}>ADRs</a>
+  </p>
+
+  <Footer />
+</Base>