maka-agent · hqhq1025 · Aug 12, 2026 · Aug 12, 2026
diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml
@@ -1,8 +1,11 @@
 name: Deploy website to GitHub Pages
 
 on:
+  pull_request:
   push:
     branches: [main]
+  schedule:
+    - cron: "23 4 * * *"
   workflow_dispatch:
 
 permissions:
@@ -32,16 +35,21 @@ jobs:
 
       - name: Build
         run: npm run build
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
 
       - name: Configure Pages
+        if: github.event_name != 'pull_request'
         uses: actions/configure-pages@v5
 
       - name: Upload Pages artifact
+        if: github.event_name != 'pull_request'
         uses: actions/upload-pages-artifact@v3
         with:
           path: dist
 
   deploy:
+    if: github.event_name != 'pull_request'
     environment:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}

diff --git a/DESIGN.md b/DESIGN.md
@@ -232,10 +232,10 @@ The system is flat by default. Depth comes from tonal separation, full-perimeter
 ### Buttons
 
 - **Shape:** Compact instrument control with a restrained curve (6px).
-- **Primary:** Zinc Ink with Clear Surface text, 14×18px padding, used for **View source**.
+- **Primary:** Zinc Ink with Clear Surface text, 14×18px padding, used for **Download Maka**.
 - **Signal:** Maka Blue with high-contrast Zinc Ink, reserved for the single active path when appropriate.
 - **Hover / Focus:** Color shifts in 140–220ms; focus uses a 2px Maka-blue outline with 3px offset. No bounce, glow, or elastic motion.
-- **Ghost:** Working Plane with a full hairline boundary, used for **Read architecture**.
+- **Ghost:** Working Plane with a full hairline boundary, used for **View source**.
 
 ### Chips
 
@@ -252,13 +252,13 @@ The system is flat by default. Depth comes from tonal separation, full-perimeter
 
 ### Navigation
 
-The fixed desktop navigation uses a compact wordmark, two evidence-led destinations, and one GitHub action. Mobile navigation keeps the GitHub action visible and collapses secondary anchors into a native `<details>` disclosure. All targets remain at least 44×44px.
+The fixed desktop navigation uses a compact wordmark, four scene destinations, a documentation path, and one GitHub action. Mobile navigation keeps the scene controls and primary actions visible. All targets remain at least 44×44px.
 
 The active single-viewport site exposes Overview, Product, Runtime, and Surfaces as `[1]`–`[4]` commands in the fixed shell. The visible hints and keyboard behavior must stay identical; Arrow keys remain a sequential alternative. Vertical wheel/trackpad gestures and touch swipes advance the same ordered state machine with an accumulator, one-step gesture lock, and non-looping edge resistance. Initial shell items reveal as one short orchestrated sequence, while `prefers-reduced-motion` renders them immediately.
 
 The shell also exposes one `THEME [T]` command beside the GitHub action. It flips the whole stage between the daylight system and a Night system built from the product's own Night Surface tokens: deep night-blue Overview atmosphere with dimmed light bands and lowered renderer exposure, Night Surface paper for Product and Surfaces, and unchanged near-black Runtime. The preference persists in `localStorage`, seeds from `prefers-color-scheme`, keeps WCAG AA contrast (verified by Axe in both themes), and follows the product's Dark Restraint Rule—tonal separation, no neon, no lifted-everything styling.
 
-Surfaces is the closing state. It returns the stage to paper, decodes the "Same runtime. Every surface." statement through a constrained glyph pool as if a recorded execution were being replayed into words, and projects one record into four asymmetric outputs: a dominant authentic Desktop crop, a TUI panel, a single CLI strip, and a compact Headless TaskRun ledger. The semantic four-entry index remains aligned to those projections, while the final source action and colophon close the story. The decode animation is Maka-original: glyphs resolve left-to-right per character, reduced motion settles the text instantly, and the semantic statement stays available to assistive technology through a static `aria-label`.
+Surfaces is the closing state. It returns the stage to paper, decodes the "Same runtime. Every surface." statement through a constrained glyph pool as if a recorded execution were being replayed into words, and projects one authority into four asymmetric outputs: a dominant authentic Desktop crop, a TUI panel, a single CLI strip, and a compact Eval cell record. The semantic four-entry index remains aligned to those projections, while the final source action and colophon close the story. The decode animation is Maka-original: glyphs resolve left-to-right per character, reduced motion settles the text instantly, and the semantic statement stays available to assistive technology through a static `aria-label`.
 
 ### Persistent Telemetry
 

diff --git a/HOMEPAGE_BRIEF.md b/HOMEPAGE_BRIEF.md
@@ -2,11 +2,11 @@
 
 ## 1. Feature Summary
 
-A production-ready, responsive brand homepage for Maka and `maka-agent.com`. It introduces a skeptical technical audience to Maka's local-first execution model, supports claims with real product and architecture evidence, and routes qualified visitors to the public GitHub repository.
+A production-ready, responsive brand homepage for Maka and `maka-agent.com`. It introduces a skeptical technical audience to Maka's local-first execution model, supports claims with real product and architecture evidence, and routes qualified visitors to the current download, documentation, and public source.
 
 ## 2. Primary User Action
 
-Understand that Maka turns agent conversations into inspectable, recoverable work, then choose **View source**. **Read architecture** is the evidence-first alternative.
+Understand that Maka turns agent conversations into inspectable, recoverable work, then choose **Download Maka**. **View source** is the evidence-first alternative.
 
 ## 3. Design Direction
 
@@ -41,7 +41,7 @@ The renderer treats pointer position as coordinates, highlights one task path, a
 
 ## 8. Content Requirements
 
-Use only claims verifiable in the official README, architecture, security, and design documentation. Required media are official screenshots of the Artifact pane, first-run provider setup, and error handling. Required copy covers local-first storage, Event Log recovery, Tool Calls and permissions, artifacts, Desktop/TUI/CLI/Headless surfaces, source-first maturity, and the GitHub/architecture CTAs. No fake customer proof, metrics, downloads, or availability promises.
+Use only claims verifiable in the official README, architecture, security, release record, and design documentation. Required media are official screenshots of the Artifact pane, first-run provider setup, and error handling. Required copy covers local-first storage, Event Log recovery, Tool Calls and permissions, artifacts, Desktop/TUI/CLI clients, Eval through Runtime Host, source-first maturity, and the download/source/architecture paths. No fake customer proof, metrics, or unsupported availability promises.
 
 ## 9. Recommended References
 

diff --git a/PRODUCT.md b/PRODUCT.md
@@ -16,7 +16,7 @@ The secondary audience is open-source contributors who need a fast path into Mak
 
 ## Product Purpose
 
-The homepage explains Maka as a local-first workspace for directing, supervising, and completing real work with agents. It must distinguish Maka from disposable chat interfaces, show how conversation, Tool Calls, permissions, artifacts, and durable task state stay connected, and make the project's current source-first maturity explicit.
+The homepage explains Maka as a local-first workspace for directing, supervising, and completing real work with agents. It must distinguish Maka from disposable chat interfaces, show how conversation, Tool Calls, permissions, artifacts, and durable execution state stay connected, and make the project's current source-first maturity explicit.
 
 Success means a visitor can understand Maka's trust model and execution model within one pass, verify the claims through real product imagery and architecture links, and confidently continue to the GitHub repository.
 
@@ -26,11 +26,11 @@ Maka turns agent work into inspectable, recoverable local execution—not dispos
 
 ## Conversion & proof
 
-- Primary CTA: **View source** at `maka-agent/maka-agent`.
-- Secondary CTA: **Read architecture** in the official repository.
+- Primary CTA: **Download Maka** from the current GitHub Release.
+- Secondary CTA: **View source** at `maka-agent/maka-agent`; architecture remains a first-class proof link.
 - The line a visitor remembers after 10 seconds: **A local-first Agent workspace built for real work.**
-- Belief ladder: Maka is more than chat → work runs locally by default → Tool Calls and permissions remain inspectable → outputs become real artifacts → event logs make progress recoverable → the implementation is open for inspection.
-- Proof on hand: the public source repository, `ARCHITECTURE.md`, `DESIGN.md`, security documentation, and official product screenshots for the Artifact pane, first-run provider setup, and honest error states. No testimonials, customer logos, adoption metrics, or release claims are available and none may be fabricated.
+- Belief ladder: Maka is more than chat → work runs locally by default → Tool Calls and permissions remain inspectable → outputs become real artifacts → event logs make progress recoverable → reproducible Eval subjects use the same Runtime Host → the implementation is open for inspection.
+- Proof on hand: the public source repository, current GitHub Release, `ARCHITECTURE.md`, `DESIGN.md`, security documentation, and official product screenshots for the Artifact pane, first-run provider setup, and honest error states. No testimonials, customer logos, adoption metrics, or unsupported availability claims may be fabricated.
 
 ## Brand Personality
 

diff --git a/README.md b/README.md
@@ -14,10 +14,15 @@ npm run dev
 ```sh
 npm run check
 npm run build
+npm run test:seo
 ```
 
 The site is an Astro static build. GitHub Actions publishes `dist/` to GitHub Pages after changes land on `main`. Cloudflare provides authoritative DNS for the custom domain; GitHub Pages terminates HTTPS.
 
+The production workflow also rebuilds daily. Release pages and machine-readable endpoints read the latest published `maka-agent/maka-agent` GitHub Release during the build, so version and installer facts remain aligned with the canonical release record.
+
+Public machine-readable endpoints include `/llms.txt`, `/llms-full.txt`, `/site.json`, and Markdown alternates for the main project pages.
+
 ## Design evidence
 
 - [`PRODUCT.md`](./PRODUCT.md) captures audience, positioning, proof, and accessibility requirements.

diff --git a/astro.config.mjs b/astro.config.mjs
@@ -8,7 +8,11 @@ export default defineConfig({
   },
   output: "static",
   compressHTML: true,
-  integrations: [sitemap()],
+  integrations: [
+    sitemap({
+      filter: (page) => !/\.(json|md|txt)$/.test(new URL(page).pathname),
+    }),
+  ],
   build: {
     inlineStylesheets: "always",
   },

diff --git a/package.json b/package.json
@@ -5,10 +5,11 @@
   "type": "module",
   "scripts": {
     "dev": "astro dev",
-    "build": "astro check && astro build",
+    "build": "astro check && astro build && node tests/seo_contract.mjs",
     "check": "astro check",
     "preview": "astro preview",
     "test:e2e": "node tests/e2e_site.mjs",
+    "test:seo": "node tests/seo_contract.mjs",
     "capture:initial-load": "node tests/capture_initial_load.mjs",
     "capture:transitions": "node tests/capture_transition_loop.mjs",
     "capture:hover": "node tests/capture_product_hover.mjs"

diff --git a/public/.well-known/security.txt b/public/.well-known/security.txt
@@ -0,0 +1,4 @@
+Contact: https://github.com/maka-agent/maka-agent/security/advisories/new
+Expires: 2027-08-12T00:00:00Z
+Canonical: https://maka-agent.com/.well-known/security.txt
+Policy: https://github.com/maka-agent/maka-agent/security/policy
diff --git a/src/components/DocumentHeader.astro b/src/components/DocumentHeader.astro
@@ -0,0 +1,31 @@
+---
+const githubUrl = "https://github.com/maka-agent/maka-agent";
+const path = Astro.url.pathname;
+const links = [
+  ["/download/", "Download"],
+  ["/docs/", "Docs"],
+  ["/architecture/", "Architecture"],
+  ["/security/", "Security"],
+  ["/releases/", "Releases"],
+] as const;
+---
+
+<header class="document-header" aria-label="Primary navigation">
+  <a class="document-brand" href="/" aria-label="Maka home">
+    <svg viewBox="0 0 34 34" aria-hidden="true">
+      <path d="M10 5H5v24h5M24 5h5v24h-5"></path>
+      <circle cx="17" cy="17" r="3"></circle>
+    </svg>
+    <span>MAKA AGENT</span>
+  </a>
+
+  <nav class="document-nav" aria-label="Project">
+    {links.map(([href, label]) => (
+      <a href={href} aria-current={path === href ? "page" : undefined}>{label}</a>
+    ))}
+  </nav>
+
+  <a class="document-source" href={githubUrl} target="_blank" rel="noreferrer">
+    Source <span aria-hidden="true">↗</span>
+  </a>
+</header>
diff --git a/src/layouts/BaseLayout.astro b/src/layouts/BaseLayout.astro
@@ -8,27 +8,54 @@ import geistMonoLatinUrl from "@fontsource-variable/geist-mono/files/geist-mono-
 interface Props {
   title: string;
   description: string;
+  lang?: string;
+  pageClass?: string;
+  canonicalPath?: string;
+  robots?: string;
+  markdownPath?: string;
+  alternateLanguages?: Array<{ lang: string; href: string }>;
+  structuredData?: Record<string, unknown>;
 }
 
-const { title, description } = Astro.props;
-const canonical = new URL(Astro.url.pathname, Astro.site);
+const {
+  title,
+  description,
+  lang = "en",
+  pageClass,
+  canonicalPath = Astro.url.pathname,
+  robots = "index, follow",
+  markdownPath,
+  alternateLanguages = [],
+  structuredData,
+} = Astro.props;
+const canonical = new URL(canonicalPath, Astro.site);
 ---
 
 <!doctype html>
-<html lang="en">
+<html lang={lang} class={pageClass}>
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />
     <meta name="theme-color" content="#c3ddf3" />
     <meta name="color-scheme" content="light" />
     <meta name="description" content={description} />
+    <meta name="robots" content={robots} />
     <meta property="og:title" content={title} />
     <meta property="og:description" content={description} />
     <meta property="og:type" content="website" />
     <meta property="og:url" content={canonical} />
     <meta property="og:site_name" content="Maka" />
+    <meta property="og:locale" content={lang === "zh-CN" ? "zh_CN" : "en_US"} />
     <meta name="twitter:card" content="summary_large_image" />
+    <meta name="twitter:title" content={title} />
+    <meta name="twitter:description" content={description} />
     <link rel="canonical" href={canonical} />
+    {alternateLanguages.map((alternate) => (
+      <link rel="alternate" hreflang={alternate.lang} href={new URL(alternate.href, Astro.site)} />
+    ))}
+    {markdownPath && (
+      <link rel="alternate" type="text/markdown" href={new URL(markdownPath, Astro.site)} />
+    )}
     <link rel="preload" as="font" type="font/woff2" href={geistLatinUrl} crossorigin />
     <link rel="preload" as="font" type="font/woff2" href={geistMonoLatinUrl} crossorigin />
     <link rel="icon" href="/favicon.png" type="image/png" sizes="48x48" />
@@ -37,7 +64,18 @@ const canonical = new URL(Astro.url.pathname, Astro.site);
     <meta property="og:image" content={new URL("/og.png", Astro.site)} />
     <meta property="og:image:width" content="2400" />
     <meta property="og:image:height" content="1260" />
+    <meta property="og:image:alt" content="Maka — local-first agent workspace" />
+    <meta name="twitter:image" content={new URL("/og.png", Astro.site)} />
     <link rel="manifest" href="/site.webmanifest" />
+    <link
+      rel="alternate"
+      type="application/atom+xml"
+      title="Maka releases"
+      href="https://github.com/maka-agent/maka-agent/releases.atom"
+    />
+    {structuredData && (
+      <script is:inline type="application/ld+json" set:html={JSON.stringify(structuredData)} />
+    )}
     <script is:inline>
       document.documentElement.classList.add("js");
       try {

diff --git a/src/layouts/ContentLayout.astro b/src/layouts/ContentLayout.astro
@@ -0,0 +1,67 @@
+---
+import BaseLayout from "./BaseLayout.astro";
+import DocumentHeader from "../components/DocumentHeader.astro";
+import "../styles/document.css";
+
+interface Props {
+  title: string;
+  description: string;
+  eyebrow: string;
+  heading: string;
+  lead: string;
+  markdownPath: string;
+  lang?: string;
+  alternateLanguages?: Array<{ lang: string; href: string }>;
+  structuredData?: Record<string, unknown>;
+}
+
+const {
+  title,
+  description,
+  eyebrow,
+  heading,
+  lead,
+  markdownPath,
+  lang,
+  alternateLanguages,
+  structuredData,
+} = Astro.props;
+---
+
+<BaseLayout
+  title={title}
+  description={description}
+  pageClass="document-page"
+  markdownPath={markdownPath}
+  lang={lang}
+  alternateLanguages={alternateLanguages}
+  structuredData={structuredData}
+>
+  <DocumentHeader />
+  <main id="main-content" class="document-shell">
+    <aside class="document-index" aria-label="Document identity">
+      <span>MAKA / PUBLIC RECORD</span>
+      <b>{Astro.url.pathname.toUpperCase()}</b>
+      <i aria-hidden="true"></i>
+    </aside>
+
+    <article class="document-article">
+      <header class="document-intro">
+        <p>{eyebrow}</p>
+        <h1>{heading}</h1>
+        <div class="document-lead">{lead}</div>
+      </header>
+      <div class="document-body">
+        <slot />
+      </div>
+    </article>
+  </main>
+
+  <footer class="document-footer">
+    <span>LOCAL EXECUTION / OPEN SOURCE</span>
+    <a href="/llms.txt">AI index</a>
+    <a href="https://github.com/maka-agent/maka-agent" target="_blank" rel="noreferrer">
+      github.com/maka-agent/maka-agent
+    </a>
+  </footer>
+</BaseLayout>