feat: establish SEO and AI visibility foundation (design WIP)

[hqhq1025]

Status

Draft: SEO/GEO infrastructure is working, but the new public pages are not visually finished.

This PR establishes indexable routes, canonical facts, release freshness, and machine-readable endpoints. The current document-page design is a first-pass information architecture used to validate content, responsive behavior, and crawler contracts. It is intentionally shown below so reviewers can evaluate the real state. The PR should not be marked ready or merged until the design and content checklist is resolved.

Public page inventory

The production links return 404 until this PR is merged and GitHub Pages deploys.

Page	Planned public URL	Source	Current role	Design status
Existing homepage	https://maka-agent.com/	src/pages/index.astro	Brand overview and primary conversion	Existing design retained; CTA and stale Headless copy updated
Download	https://maka-agent.com/download/	src/pages/download.astro	Current installers, checksums, platform limits	First-pass, needs stronger product and trust treatment
Documentation	https://maka-agent.com/docs/	src/pages/docs.astro	Public documentation authority map	First-pass, too close to a link directory
Architecture	https://maka-agent.com/architecture/	src/pages/architecture.astro	Runtime Host and execution model	First-pass, needs diagrams and better evidence
Security	https://maka-agent.com/security/	src/pages/security.astro	Current security and privacy boundaries	First-pass, text-heavy and visually flat
Releases	https://maka-agent.com/releases/	src/pages/releases.astro	Current version and release artifacts	First-pass, currently reads like an asset dump
Chinese overview	https://maka-agent.com/zh/	src/pages/zh/index.astro	Chinese project entity page	First-pass, typography and content depth need revision

Shared page implementation:

• src/layouts/ContentLayout.astro
• src/components/DocumentHeader.astro
• src/styles/document.css
• src/layouts/BaseLayout.astro

Current visual state

These screenshots are the current implementation, not target mocks.

Download: desktop and mobile

Documentation: desktop and mobile

Architecture: desktop and mobile

Security: desktop and mobile

Releases: desktop and mobile

Chinese overview: desktop and mobile

Known design and content gaps

Before ready for review:

• Give each page a page-specific visual argument instead of reusing one giant-heading document template everywhere.
• Fix the mobile navigation: the horizontally scrolling labels currently crop the final items and do not communicate that more navigation exists.
• Rework Chinese display typography and line breaking; the current large heading is too dense and breaks awkwardly.
• Make Download a product decision page with clearer platform hierarchy, installer trust, checksums, limitations, and an intentional primary action.
• Turn Documentation into a navigable content map with stronger grouping and orientation.
• Add an actual architecture diagram or execution evidence to Architecture; the current text and code block are insufficient.
• Improve Security hierarchy with explicit current guarantees, known limitations, and reporting flow without turning it into generic trust marketing.
• Redesign Releases around the current release, platform artifacts, checksums, and history rather than exposing a flat asset list.
• Add stronger cross-page next steps and preserve a clear route back to the immersive homepage.
• Review all public claims against the current main repository before final copy approval.
• Repeat desktop/mobile screenshot review after the visual pass.

The crawler contracts and content sources should remain stable while these pages are redesigned.

Machine-readable inventory

Endpoint	Purpose
https://maka-agent.com/llms.txt	Concise AI-readable site and entity index
https://maka-agent.com/llms-full.txt	Fuller public project context
https://maka-agent.com/site.json	Structured project, release, page, and artifact data
https://maka-agent.com/project.md	Canonical Markdown project summary
/download.md, /docs.md, /architecture.md, /security.md, /releases.md, /zh.md	Page-level Markdown alternatives
https://maka-agent.com/.well-known/security.txt	Security contact and policy discovery
https://maka-agent.com/sitemap-index.xml	Canonical HTML page discovery

Infrastructure included

• Current release data is fetched from the official maka-agent/maka-agent GitHub Release during the build.
• The production workflow rebuilds daily so version, installer, checksum, and publication facts do not stay stale.
• Every public HTML page has title, description, canonical, robots, Open Graph, Twitter, JSON-LD, and a Markdown alternate.
• The 404 page uses noindex, nofollow.
• The sitemap includes canonical HTML routes and excludes machine endpoints.
• The homepage now points to Download and Docs and describes Eval through Runtime Host instead of the stale Headless model.
• tests/seo_contract.mjs fails the build when required routes or metadata disappear.

Verification completed

• npm run build
• MAKA_SITE_URL=http://127.0.0.1:4327 npm run test:e2e
• Existing homepage tested at 320, 390, 768, 1280, 1440, and 1920 px
• WebGL, static fallback, reduced motion, keyboard navigation, and Axe checks passed
• 12 desktop/mobile document-page renders completed without horizontal overflow, console errors, missing canonical links, missing JSON-LD, or missing Markdown alternatives
• All JSON-LD and site.json payloads parse successfully
• PR build check is green

Merge and deployment

• Keep this PR as Draft while the page design and content gaps above remain open.
• The new routes remain unavailable on maka-agent.com until this PR is merged and the GitHub Pages deployment completes.
• maka-agent/maka-agent#2924 depends on these routes and is also Draft.
• The build uses GITHUB_TOKEN for release metadata and fails instead of publishing stale release facts.

[Autonomy-Labs-Tech]

I built an AI Agent Readiness Audit service that checks exactly the surfaces you need for AI visibility: llms.txt, robots.txt, sitemap.xml, .well-known/x402, and agents.txt. It gives you a grade and specific fixes. Try it: https://x402-audit-landing-mivdylf55-lasse-tfa.vercel.app - only $0.01 USDC per audit on Base. This could help with your SEO and AI visibility foundation.