From 19715e0997348343ee80c3d64b76febf80c55e61 Mon Sep 17 00:00:00 2001
From: James Dansereau <106631954+jkdansereau@users.noreply.github.com>
Date: Wed, 2 Sep 2026 17:47:18 -0400
Subject: [PATCH] docs(pages): SEO setup + Cayman design pass

_config.yml:
- canonical url/baseurl for jekyll-seo-tag + jekyll-sitemap
- jekyll-seo-tag + jekyll-sitemap plugins; og:image link-preview card
- keep the raw engineering record (dev/ finding log, per-level status,
  triage notes) out of sitemap.xml; keep the two linked dev/ docs in

_includes/head-custom.html:
- Google/Bing Search Console verification tags
- full design pass over the stock Cayman theme: IBM Plex Sans/Mono,
  restrained amber-on-slate palette, light + dark themes, faded
  attract-mode screenshot header treatment, tightened typographic
  hierarchy, dark code blocks, quieter tables
---
 docs/_config.yml                |  35 +++++
 docs/_includes/head-custom.html | 253 ++++++++++++++++++++++++++++++++
 2 files changed, 288 insertions(+)
 create mode 100644 docs/_includes/head-custom.html

diff --git a/docs/_config.yml b/docs/_config.yml
index bf3cd7f7..7823e111 100644
--- a/docs/_config.yml
+++ b/docs/_config.yml
@@ -8,9 +8,44 @@ description: >-
 theme: jekyll-theme-cayman
 show_downloads: false
 
+# Canonical site location - used by jekyll-seo-tag (canonical URLs, og: tags)
+# and jekyll-sitemap (absolute URLs in sitemap.xml).
+url: https://jkdansereau.github.io
+baseurl: /goldeneye-pc-port
+
+# Link-preview card image for jekyll-seo-tag (og:image / twitter:image).
+# Path is relative to the site root; the plugin prepends url + baseurl.
+image: /img/attract-bunker1.png
+
+# Both are on the GitHub Pages plugin whitelist - no Gemfile needed.
+# jekyll-seo-tag: per-page <title>/description/canonical/OpenGraph via {% seo %}
+#   (already emitted by the Cayman layout).
+# jekyll-sitemap: generates /sitemap.xml for Search Console / Bing submission.
+plugins:
+  - jekyll-seo-tag
+  - jekyll-sitemap
+
 # jekyll-relative-links (on by default for Pages) rewrites the .md links in
 # these docs to .html so cross-links work on the published site.
 
 # Rolling local working files - not useful as published pages.
 exclude:
   - HANDOFF.md
+
+# Keep the raw engineering record (finding log, per-level status, triage
+# notes, backlogs) out of sitemap.xml so search engines aren't steered at it.
+# The pages still build and stay reachable from cross-links; the two dev/
+# docs that are linked from the site index are kept in.
+defaults:
+  - scope:
+      path: "dev"
+    values:
+      sitemap: false
+  - scope:
+      path: "dev/agentic-development.md"
+    values:
+      sitemap: true
+  - scope:
+      path: "dev/game-behavior-reference.md"
+    values:
+      sitemap: true
diff --git a/docs/_includes/head-custom.html b/docs/_includes/head-custom.html
new file mode 100644
index 00000000..c8965e02
--- /dev/null
+++ b/docs/_includes/head-custom.html
@@ -0,0 +1,253 @@
+<meta name="google-site-verification" content="UlOGMwqwnUbviaX7-HY3f-fXedkSHyxAPTO0zNHNrfc" />
+<meta name="msvalidate.01" content="E819A8FD183E027D96725C924D4822BD" />
+
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+<link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Sans:wght@400;500;600;700&family=IBM+Plex+Mono:wght@400;500&display=swap" rel="stylesheet">
+
+<style>
+  /* ----------------------------------------------------------------------
+     Design pass over the stock Cayman theme.
+     Restrained "spy-tech" palette: near-black, slate, a single amber accent.
+     Loaded after the theme stylesheet, so these rules win without !important.
+     --------------------------------------------------------------------- */
+  :root {
+    color-scheme: light dark;
+    --ink:        #14171c;
+    --ink-soft:   #3d444d;
+    --ink-mute:   #626b76;
+    --line:       #e4e6e9;
+    --bg:         #ffffff;
+    --bg-soft:    #f7f8fa;
+    --accent:     #b7791f;
+    --accent-ink: #8a5a12;
+    --header-1:   #0d1117;
+    --header-2:   #1c2530;
+    --radius:     8px;
+    --measure:    44rem;
+  }
+
+  @media (prefers-color-scheme: dark) {
+    :root {
+      --ink:      #e7eaee;
+      --ink-soft: #b9c0c9;
+      --ink-mute: #8b939e;
+      --line:     #2a2f37;
+      --bg:       #0f1216;
+      --bg-soft:  #171b21;
+      --accent:   #e0a94a;
+      --accent-ink: #f0c274;
+      --header-1: #0a0d11;
+      --header-2: #161d27;
+    }
+  }
+
+  body {
+    font-family: "IBM Plex Sans", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+    color: var(--ink);
+    background: var(--bg);
+    font-size: 17px;
+    line-height: 1.7;
+    -webkit-font-smoothing: antialiased;
+    text-rendering: optimizeLegibility;
+  }
+
+  /* ---- Header --------------------------------------------------------- */
+  .page-header {
+    position: relative;
+    isolation: isolate;
+    text-align: center;
+    padding: 4rem 1rem 3.75rem;
+    background: linear-gradient(135deg, var(--header-1), var(--header-2));
+    border-bottom: 1px solid rgba(224, 169, 74, 0.28);
+  }
+  .page-header::before {
+    content: "";
+    position: absolute;
+    inset: 0;
+    z-index: -1;
+    background-image: url("{{ '/img/attract-bunker1.png' | relative_url }}");
+    background-size: cover;
+    background-position: center 38%;
+    opacity: 0.16;
+    filter: grayscale(0.35) contrast(1.05);
+  }
+  .page-header::after {
+    content: "";
+    position: absolute;
+    inset: 0;
+    z-index: -1;
+    background: linear-gradient(180deg, rgba(13,17,23,0.35), rgba(13,17,23,0.82));
+  }
+  .project-name {
+    font-weight: 700;
+    letter-spacing: -0.02em;
+    font-size: 2.4rem;
+    margin: 0 0 0.4rem;
+    color: #fff;
+    text-shadow: 0 1px 24px rgba(0,0,0,0.5);
+  }
+  .project-tagline {
+    font-weight: 400;
+    font-size: 1.12rem;
+    line-height: 1.55;
+    color: #d3d9e0;
+    opacity: 1;
+    max-width: 42rem;
+    margin: 0 auto 1.6rem;
+  }
+  .page-header .btn {
+    display: inline-block;
+    padding: 0.5rem 1.1rem;
+    margin: 0.3rem 0.25rem 0;
+    font-size: 0.9rem;
+    font-weight: 500;
+    letter-spacing: 0.01em;
+    color: #f3f5f7;
+    background: rgba(255,255,255,0.06);
+    border: 1px solid rgba(255,255,255,0.22);
+    border-radius: var(--radius);
+    transition: background 0.15s ease, border-color 0.15s ease, transform 0.15s ease;
+  }
+  .page-header .btn:hover {
+    background: rgba(224,169,74,0.16);
+    border-color: var(--accent);
+    text-decoration: none;
+    transform: translateY(-1px);
+  }
+
+  /* ---- Body ---------------------------------------------------------- */
+  .main-content {
+    max-width: 52rem;
+    margin: 0 auto;
+    padding: 3rem 1.5rem 1rem;
+    color: var(--ink);
+    font-size: 17px;
+  }
+  .main-content p,
+  .main-content ul,
+  .main-content ol,
+  .main-content blockquote { max-width: var(--measure); }
+
+  .main-content h1,
+  .main-content h2,
+  .main-content h3,
+  .main-content h4 {
+    color: var(--ink);
+    font-weight: 600;
+    letter-spacing: -0.015em;
+    line-height: 1.3;
+    margin-top: 2.4rem;
+  }
+  .main-content h1 { font-size: 1.9rem; }
+  .main-content h2 {
+    font-size: 1.4rem;
+    padding-bottom: 0.35rem;
+    border-bottom: 1px solid var(--line);
+  }
+  .main-content h3 { font-size: 1.15rem; }
+  .main-content > h1:first-child { margin-top: 0.5rem; }
+
+  .main-content a {
+    color: var(--accent-ink);
+    text-decoration: underline;
+    text-decoration-color: rgba(183,121,31,0.4);
+    text-underline-offset: 2px;
+  }
+  .main-content a:hover {
+    color: var(--accent);
+    text-decoration-color: currentColor;
+  }
+  @media (prefers-color-scheme: dark) {
+    .main-content a { color: var(--accent); }
+  }
+
+  .main-content blockquote {
+    color: var(--ink-mute);
+    border-left: 3px solid var(--accent);
+    padding: 0.2rem 0 0.2rem 1.1rem;
+    margin-left: 0;
+    font-style: normal;
+  }
+
+  .main-content hr {
+    height: 1px;
+    background: var(--line);
+    border: 0;
+    margin: 2.5rem 0;
+  }
+
+  /* Lead paragraph on doc pages (the italic summary under the H1) */
+  .main-content > p > em:only-child {
+    font-style: normal;
+    color: var(--ink-soft);
+    font-size: 1.05rem;
+  }
+
+  /* ---- Code --------------------------------------------------------- */
+  .main-content code {
+    font-family: "IBM Plex Mono", ui-monospace, SFMono-Regular, Menlo, monospace;
+    font-size: 0.86em;
+    background: var(--bg-soft);
+    border: 1px solid var(--line);
+    border-radius: 4px;
+    padding: 0.12em 0.4em;
+    color: var(--ink);
+  }
+  .main-content pre {
+    background: var(--header-1);
+    border: 1px solid var(--line);
+    border-radius: var(--radius);
+    padding: 1rem 1.15rem;
+    max-width: var(--measure);
+    overflow-x: auto;
+  }
+  .main-content pre code {
+    background: transparent;
+    border: 0;
+    padding: 0;
+    color: #e6edf3;
+    font-size: 0.84rem;
+  }
+
+  /* ---- Tables ------------------------------------------------------- */
+  .main-content table {
+    border-collapse: collapse;
+    display: table;
+    width: 100%;
+    max-width: var(--measure);
+    margin: 1.5rem 0;
+    font-size: 0.92rem;
+  }
+  .main-content table th,
+  .main-content table td {
+    border: 1px solid var(--line);
+    padding: 0.5rem 0.75rem;
+  }
+  .main-content table th { background: var(--bg-soft); font-weight: 600; }
+  .main-content table tr { background: transparent; }
+  .main-content table tr:nth-child(2n) { background: var(--bg-soft); }
+
+  .main-content img {
+    border-radius: var(--radius);
+    border: 1px solid var(--line);
+  }
+
+  /* ---- Footer ------------------------------------------------------- */
+  .site-footer {
+    max-width: 52rem;
+    margin: 3rem auto 0;
+    padding: 1.5rem 1.5rem 2.5rem;
+    border-top: 1px solid var(--line);
+    color: var(--ink-mute);
+    font-size: 0.86rem;
+  }
+  .site-footer a { color: var(--accent-ink); }
+  @media (prefers-color-scheme: dark) { .site-footer a { color: var(--accent); } }
+
+  @media (max-width: 42rem) {
+    .project-name { font-size: 1.9rem; }
+    .page-header { padding: 3rem 1rem 2.75rem; }
+    .main-content { padding-top: 2rem; }
+  }
+</style>