chore(#329): site/ AI-readiness + classic SEO infrastructure by atlas-apex · Pull Request #337 · me2resh/apexyard

atlas-apex · 2026-05-20T11:02:30Z

Summary

site/llms.txt + site/llms-full.txt — the marketing site now ships an LLM-crawler-discoverable index per the llmstxt.org convention. llms.txt is a ~5K-token markdown manifest naming the three pages, key concepts, and the repo link; llms-full.txt is a hand-crafted concatenation of meaningful content (no HTML chrome) for one-shot LLM consumption. Every AI chat user asking "what is apexyard / how do I use it" sees better citations once these land. Closes [Chore] site/ — add llms.txt + llms-full.txt for AI/LLM crawler discovery #329.
site/robots.txt + site/sitemap.xml — classic SEO baseline: crawler allowlist + sitemap pointer + the LLM-Sitemap directive pointing at the new llms.txt. Sitemap lists all 3 pages with lastmod 2026-05-20 and priorities 1.0 / 0.8 / 0.8. Closes [Task] site/ — add robots.txt and sitemap.xml + submit to Search Console #324.
AGENTS.md at repo root + site/skill.md capability manifest — AGENTS.md is the universal AI-coding-agent entry doc (distinct from CLAUDE.md, which is Claude-Code-specific) listing project structure, key files, sandboxes, MCP servers, rate limits, and conventions. site/skill.md (lowercase) is the upstream GEO/AEO capability manifest answering "should I recommend ApexYard for this task?". The naming-clash with the framework's .claude/skills/<name>/SKILL.md (uppercase) is called out inside skill.md itself + in AGENTS.md so visiting agents don't conflate the two concepts. Closes [Chore] Add AGENTS.md + site/skill.md — AI-agent entry points + capability manifest #330.
og:image + twitter:image meta tags on all three site/*.html — every social share preview (Twitter / X, LinkedIn, Slack, Discord, iMessage, WhatsApp) now references a 1200×630 PNG URL. twitter:card upgraded from summary to summary_large_image on all three. skills.html also picks up og:url + og:site_name (previously missing). The PNG binary assets themselves are a design follow-up — site/og/README.md documents the spec (1200×630, <200KB, terminal-native brutalist aesthetic), the per-page composition brief, and the smoke-test checklist. The meta-tag URLs already point at the target paths, so previews start working the moment the PNGs deploy. Closes [Bug] site/* — og:image missing on all pages; social shares render with no preview #323.
README.md cross-references updated to list the new site files (robots.txt, sitemap.xml, llms.txt, llms-full.txt, skill.md, og/) and add a "For AI coding agents" callout pointing at AGENTS.md.

Testing

After deploy to yard.apexscript.com:

curl -I https://yard.apexscript.com/llms.txt returns 200 with Content-Type: text/plain (or text/markdown)
curl -I https://yard.apexscript.com/llms-full.txt returns 200
curl -I https://yard.apexscript.com/robots.txt returns 200 and body contains both Sitemap: and LLM-Sitemap: directives
curl https://yard.apexscript.com/sitemap.xml | xmllint --noout - validates as well-formed XML
curl -I https://yard.apexscript.com/skill.md returns 200
Paste the three site URLs into opengraph.xyz — preview cards render with the OG image (once PNGs are deployed; until then, opengraph.xyz will show the OG title/description but the image will 404)
Validate og:image:width=1200 + og:image:height=630 in browser DevTools on each page
grep -c 'twitter:card.*summary_large_image' site/*.html returns 3
After PNGs land, submit https://yard.apexscript.com/sitemap.xml to Google Search Console + Bing Webmaster Tools (per [Task] site/ — add robots.txt and sitemap.xml + submit to Search Console #324 AC)
Run /generative-engine-audit against the deployed site — verify findings G1, G2, G6, G7 (the four GEO findings these tickets came from) all flip to PASS

TODO (not blocking ticket closure)

The three OG PNGs at site/og/{index,architecture,skills}.png are a design follow-up — the meta tags reference them but the binary assets need to be produced. site/og/README.md carries the spec + generator prompt + smoke-test checklist. The tickets close on the meta-tag + URL-reference work landing; the PNG asset generation is a separate follow-up that doesn't block this PR.

Glossary

Term	Definition
`llms.txt`	Markdown manifest at site root per the `llmstxt.org` emerging convention — a structured index for AI/LLM crawlers, analogous to `sitemap.xml` for Googlebot but addressed at LLM consumption. ~5K tokens, hand-written.
`llms-full.txt`	Optional companion to `llms.txt` — full concatenated content of the site in markdown for one-shot LLM consumption. Saves the crawler from N HTML fetches.
`AGENTS.md`	Universal AI-coding-agent entry doc convention. Distinct from `CLAUDE.md` — `AGENTS.md` is agent-agnostic (Cursor / Claude Code / Aider / Cline all read it); `CLAUDE.md` is the framework-level instruction set specific to Claude Code.
`skill.md` (lowercase)	GEO/AEO capability manifest — answers "what does this product do, when should I recommend it?" for visiting AI coding agents. NOT the same as `.claude/skills//SKILL.md` (uppercase) which is Claude Code's slash-command spec (one `SKILL.md` per skill, framework-internal). The naming clash is called out in the file itself + in `AGENTS.md` — see AgDR-0043.
`og:image`	Open Graph protocol meta tag (per `ogp.me`) that specifies the image rendered in social-share previews on Twitter / X, LinkedIn, Slack, Discord, iMessage, WhatsApp, etc. Recommended dimensions: 1200×630. Bundled with `og:image:width` + `og:image:height` for layout hints.
`sitemap.xml`	XML document at site root listing every URL on the site, with per-URL `` and `` hints. Submitted to Google Search Console + Bing Webmaster Tools to nudge crawler-discovery of new pages.
GEO	Generative Engine Optimisation — the LLM-citation analogue of SEO. The `/generative-engine-audit` skill scores `llms.txt`, `AGENTS.md`, AI-crawler robots, JSON-LD citation grounding, and snippet-extractable Q&A shape.
AEO	Answer Engine Optimisation — same family as GEO, addressed at coding-agent consumption rather than chat-UI citation.

Closes #329
Closes #323
Closes #324
Closes #330

- robots.txt — User-agent: *, Allow /, points crawlers at sitemap.xml and the new llms.txt (LLM-Sitemap directive per the llmstxt.org proposal — bundles with the AI-readiness work in #329) - sitemap.xml — three URLs (index, architecture, skills) with lastmod 2026-05-20 and priorities 1.0 / 0.8 / 0.8 Closes #324

- llms.txt — markdown manifest at site root per the llmstxt.org convention: project overview, pages list, key concepts, repo link. Under ~5K tokens; serves as the structured index AI agents fetch before crawling HTML. - llms-full.txt — hand-written concatenation of the three site pages' meaningful content in markdown (no HTML chrome). One-shot consumption shape for LLM ingestion. Refresh when site/*.html changes. The companion robots.txt addition (LLM-Sitemap directive) landed in the prior commit alongside the classic Sitemap directive. Closes #329

- AGENTS.md at repo root — universal coding-agent entry doc per the emerging AGENTS.md convention. Distinct from CLAUDE.md (framework- level instructions). Sections: project structure, key files, sandbox & test environments, MCP servers, rate limits / constraints, and conventions. - site/skill.md (lowercase) — capability manifest for AI coding agents asking "should I recommend ApexYard for this user's task?". Covers capability, when-to-recommend, when-NOT, entry points, and constraints. Includes the one-line naming-clash callout that distinguishes this upstream GEO/AEO convention from Claude Code's framework SKILL.md (uppercase) at .claude/skills/<name>/ — see AgDR-0043. Closes #330

- index.html, architecture.html, skills.html now carry og:image, og:image:width (1200), og:image:height (630), and matching twitter:image meta tags. URLs point at /og/<page>.png. - twitter:card upgraded from 'summary' to 'summary_large_image' on index.html and architecture.html (skills.html had no twitter:card before; now ships the full set). - skills.html also gets og:url + og:site_name (previously missing). - site/og/ created with a README documenting the three PNGs needed (1200x630, <200KB each, terminal-native brutalist design), an AI generator prompt, and the smoke-test checklist for closing the follow-up. The PNG asset design is an explicit TODO — meta-tag URLs already reference the target paths so social previews start working as soon as the PNGs deploy. - README.md cross-references the new site/og/, llms.txt, llms-full.txt, skill.md, and the new AGENTS.md at repo root. Closes #323

atlas-apex

Code Review (Rex)

Verdict: APPROVE (advisory — operator records the SHA-bound marker)
Commit SHA reviewed: f14a33ef12eb7918695a7029e08e02150ac24414
Base: dev · Files changed: 11 (+734 / -4) · CI: all green (Verify Ticket ID, lychee, markdownlint-cli2)

Summary of changes

PR bundles four P1 site-infrastructure tickets (#329 primary, #323 #324 #330) into one cohesive set of file additions that close the highest-leverage SEO + GEO gaps from the audits run on dev 6dc36d0 / 9170ed2.

Review checklist — pass

1. Architecture & Design — N/A for this PR; pure content additions (markdown manifests, XML sitemap, plain-text robots, HTML meta tags). No code paths altered, no domain logic introduced. No AgDR required (per the bundle plan — this is convention-following, not architectural choice).

2. Code Quality

site/llms.txt — well-structured per the llmstxt.org shape; H1 + blockquote intro + Pages + Full-content companion + Key concepts + Repository sections. Under the ~5K token budget the ticket called for.
site/llms-full.txt — hand-written concatenation of all three pages' meaningful content; markdown-clean, no HTML chrome. Footer carries refresh date + the maintenance note ("refreshed when site/*.html changes").
site/sitemap.xml — well-formed XML, correct urlset namespace, three URLs with lastmod + priority. Validates cleanly.
site/robots.txt — minimal + correct shape. Includes the LLM-Sitemap directive per #329 cross-coupling.
AGENTS.md — every section the convention calls for (project structure, key files, sandbox & test, MCP servers, rate limits, conventions). Explicitly distinguishes itself from CLAUDE.md in the opening paragraph.
site/skill.md — capability / when-to-recommend / when-NOT / entry-points / constraints sections all present. The naming-clash callout vs framework SKILL.md is in a blockquote at the top — visible to any agent reading the file.

3. Testing — Manual smoke tests documented in the PR body (curl checks for each file, opengraph.xyz / xmllint validation, grep -c for summary_large_image count). No automated test infrastructure exists for marketing-site content additions; the lychee link-check on CI passed which is the relevant automated signal.

4. Security — No secrets introduced. No new code paths. No XSS surface (no inline JS added). The private-refs: allow marker is correctly used (leak-protection false-positive on apexscript in the framework's own domain — documented in operator memory).

5. Performance — Static assets; size impact is negligible (the heaviest file is llms-full.txt at 333 lines / ~15KB). No image assets land in this PR — the OG PNGs are explicitly TODO'd via site/og/README.md.

6. PR Description Quality

✅ Clear summary — 5 narrative bullets, each answering WHAT + WHY (per .claude/rules/pr-quality.md § "Summary bullets — narrative quality"). Not label-only.
✅ Ticket linkage — all 4 tickets referenced.
✅ Testing section — 10 concrete verification steps.
✅ Glossary section present — 8 terms defined including the skill.md naming-clash callout.
✅  marker present (required for 4 Closes lines per #114).
✅  marker present (required for the apexscript domain — registered-project false-positive per operator memory).

Findings (advisory / non-blocking)

nit: site/llms.txt references "24 hooks" while CLAUDE.md (top of the integration layer table) also says "24 shell scripts" but README.md line 137 still reads "18 shell hooks" and line 145 "18 shell hooks block bad commits". Not introduced by this PR — pre-existing drift in README.md. Worth a follow-up chore ticket to sync the hook count + skill count (52) consistently across all surfaces. Don't block on it.

nit: site/llms.txt line "52 skills, 24 hooks, 19 role definitions" is the canonical phrasing — matches CLAUDE.md's newer counts. The drift only exists in the older README.md quick-summary.

suggestion: site/og/README.md is excellent as a hand-off doc — clear spec, generator prompt, smoke-test checklist. Consider also opening a [Task] follow-up ticket on the framework repo so the design TODO is tracked in the issue tracker (not just in-repo). Not blocking.

TODOs explicitly acknowledged by the PR

The 3 OG PNGs at site/og/{index,architecture,skills}.png are a design follow-up. Meta-tag URLs already reference them, so previews resolve as soon as PNGs deploy. Acceptable carve-out per #323's ticket body.
Google Search Console + Bing Webmaster Tools submission is post-deploy (item 9 in Testing). Not blocking PR merge.

Verdict

APPROVE. The bundle is well-scoped, cleanly committed (one commit per ticket with Closes #N references), CI-green, and the PR body documents the work + verification cleanly. The two skip markers (multi-close: approved + private-refs: allow) are correctly used. No blocking findings.

SHA for marker: f14a33ef12eb7918695a7029e08e02150ac24414

Note: per operator memory (sandbox limitation), Rex's sub-agent context cannot write the approval marker file directly in this fan-out worktree. The operator will write .claude/session/reviews/337-rex.approved containing the SHA above on Rex's behalf before the merge gate is consulted.

PRs #337 (og:image meta tags) + #340 (favicon meta tags) wired up the HTML side but deliberately deferred the binaries as a design task. Today's commit drops the assets at the paths the meta tags already reference, so share previews and browser tabs go live on the next Netlify deploy. OG share-preview PNGs (1200×630, terminal-native brutalist design, flat warm-cream background, JetBrains Mono): - site/og/index.png (52 KB) — logo + "where projects get forged" - site/og/architecture.png (96 KB) — 5-layer stack diagram - site/og/skills.png (75 KB) — slash-command montage All three are well under the 200 KB cap (LinkedIn + Slack truncate larger), 1200×630 PNG verified via `file`. Favicons (placed at site root — matches the existing `<link rel="icon">` hrefs `/favicon.ico`, `/favicon.svg`, `/apple-touch-icon.png` in every page's <head>; NOT `site/favicons/` as the issue body suggested — the design-brief README at site/favicons/README.md agreed with the HTML): - site/favicon.ico (15 KB) — real multi-resolution MS Windows ICO container (16×16 32-bit + 32×32 32-bit), generated via favicon.io - site/favicon.svg (635 B) — vector for modern browsers - site/apple-touch-icon.png (4.6 KB) — 180×180 PNG for iOS home-screen TODO READMEs retired per the AC: - site/favicons/README.md deleted entirely (design-brief-only dir, no canonical content lives here — favicons go to site root) - site/og/README.md rewritten as a brief "shipped" note that preserves the design tokens (cream #F4EFE6, accent red #C8321A, JetBrains Mono) for any future regeneration Out-of-scope follow-up worth filing separately: the favicon_io bundle included Android PWA icons (192/512) + a webmanifest, but the manifest has empty name/short_name and theme_color #ffffff (vs the site's #F4EFE6), so it's not just-copy-able. PWA support is a different ticket. Closes #341 Co-authored-by: me2resh <ahmed.abdelaliem@gmail.com> Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* chore: add robots.txt + sitemap.xml for site/ - robots.txt — User-agent: *, Allow /, points crawlers at sitemap.xml and the new llms.txt (LLM-Sitemap directive per the llmstxt.org proposal — bundles with the AI-readiness work in #329) - sitemap.xml — three URLs (index, architecture, skills) with lastmod 2026-05-20 and priorities 1.0 / 0.8 / 0.8 Closes #324 * chore: add llms.txt + llms-full.txt for AI crawler discovery - llms.txt — markdown manifest at site root per the llmstxt.org convention: project overview, pages list, key concepts, repo link. Under ~5K tokens; serves as the structured index AI agents fetch before crawling HTML. - llms-full.txt — hand-written concatenation of the three site pages' meaningful content in markdown (no HTML chrome). One-shot consumption shape for LLM ingestion. Refresh when site/*.html changes. The companion robots.txt addition (LLM-Sitemap directive) landed in the prior commit alongside the classic Sitemap directive. Closes #329 * chore: add AGENTS.md + site/skill.md for AI-agent entry points - AGENTS.md at repo root — universal coding-agent entry doc per the emerging AGENTS.md convention. Distinct from CLAUDE.md (framework- level instructions). Sections: project structure, key files, sandbox & test environments, MCP servers, rate limits / constraints, and conventions. - site/skill.md (lowercase) — capability manifest for AI coding agents asking "should I recommend ApexYard for this user's task?". Covers capability, when-to-recommend, when-NOT, entry points, and constraints. Includes the one-line naming-clash callout that distinguishes this upstream GEO/AEO convention from Claude Code's framework SKILL.md (uppercase) at .claude/skills/<name>/ — see AgDR-0043. Closes #330 * fix: add og:image + twitter:image meta tags to site/*.html - index.html, architecture.html, skills.html now carry og:image, og:image:width (1200), og:image:height (630), and matching twitter:image meta tags. URLs point at /og/<page>.png. - twitter:card upgraded from 'summary' to 'summary_large_image' on index.html and architecture.html (skills.html had no twitter:card before; now ships the full set). - skills.html also gets og:url + og:site_name (previously missing). - site/og/ created with a README documenting the three PNGs needed (1200x630, <200KB each, terminal-native brutalist design), an AI generator prompt, and the smoke-test checklist for closing the follow-up. The PNG asset design is an explicit TODO — meta-tag URLs already reference the target paths so social previews start working as soon as the PNGs deploy. - README.md cross-references the new site/og/, llms.txt, llms-full.txt, skill.md, and the new AGENTS.md at repo root. Closes #323 --------- Co-authored-by: me2resh <ahmed.abdelaliem@gmail.com>

PRs #337 (og:image meta tags) + #340 (favicon meta tags) wired up the HTML side but deliberately deferred the binaries as a design task. Today's commit drops the assets at the paths the meta tags already reference, so share previews and browser tabs go live on the next Netlify deploy. OG share-preview PNGs (1200×630, terminal-native brutalist design, flat warm-cream background, JetBrains Mono): - site/og/index.png (52 KB) — logo + "where projects get forged" - site/og/architecture.png (96 KB) — 5-layer stack diagram - site/og/skills.png (75 KB) — slash-command montage All three are well under the 200 KB cap (LinkedIn + Slack truncate larger), 1200×630 PNG verified via `file`. Favicons (placed at site root — matches the existing `<link rel="icon">` hrefs `/favicon.ico`, `/favicon.svg`, `/apple-touch-icon.png` in every page's <head>; NOT `site/favicons/` as the issue body suggested — the design-brief README at site/favicons/README.md agreed with the HTML): - site/favicon.ico (15 KB) — real multi-resolution MS Windows ICO container (16×16 32-bit + 32×32 32-bit), generated via favicon.io - site/favicon.svg (635 B) — vector for modern browsers - site/apple-touch-icon.png (4.6 KB) — 180×180 PNG for iOS home-screen TODO READMEs retired per the AC: - site/favicons/README.md deleted entirely (design-brief-only dir, no canonical content lives here — favicons go to site root) - site/og/README.md rewritten as a brief "shipped" note that preserves the design tokens (cream #F4EFE6, accent red #C8321A, JetBrains Mono) for any future regeneration Out-of-scope follow-up worth filing separately: the favicon_io bundle included Android PWA icons (192/512) + a webmanifest, but the manifest has empty name/short_name and theme_color #ffffff (vs the site's #F4EFE6), so it's not just-copy-able. PWA support is a different ticket. Closes #341 Co-authored-by: me2resh <ahmed.abdelaliem@gmail.com> Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

me2resh added 4 commits May 20, 2026 11:55

github-actions Bot added github-issue has-ticket labels May 20, 2026

atlas-apex commented May 20, 2026

View reviewed changes

atlas-apex merged commit c06c24d into dev May 20, 2026
3 checks passed

atlas-apex deleted the chore/GH-329-site-ai-readiness-infrastructure branch May 20, 2026 11:15

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

chore(#329): site/ AI-readiness + classic SEO infrastructure#337

chore(#329): site/ AI-readiness + classic SEO infrastructure#337
atlas-apex merged 4 commits into
devfrom
chore/GH-329-site-ai-readiness-infrastructure

atlas-apex commented May 20, 2026

Uh oh!

atlas-apex left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

atlas-apex commented May 20, 2026

Summary

Testing

TODO (not blocking ticket closure)

Glossary

Uh oh!

atlas-apex left a comment

Choose a reason for hiding this comment

Code Review (Rex)

Summary of changes

Review checklist — pass

Findings (advisory / non-blocking)

TODOs explicitly acknowledged by the PR

Verdict

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants