solrevdev · solrevdev · Sep 13, 2026 · Jun 24, 2026 · Jun 24, 2026 · Jun 24, 2026
diff --git a/.gitattributes b/.gitattributes
@@ -31,6 +31,7 @@
 *.jpg filter=lfs diff=lfs merge=lfs -text
 *.pdf filter=lfs diff=lfs merge=lfs -text
 *.png filter=lfs diff=lfs merge=lfs -text
+/og-image.png -filter -diff -merge -text
 *.psd filter=lfs diff=lfs merge=lfs -text
 *.webp filter=lfs diff=lfs merge=lfs -text
 

diff --git a/.github/workflows/github_workflows_build.yml b/.github/workflows/github_workflows_build.yml
@@ -27,6 +27,8 @@ jobs:
         steps:
             - name: Checkout this repo
               uses: actions/checkout@v4
+              with:
+                  fetch-depth: 0
 
             - name: Cache winget-pkgs repo
               uses: actions/cache@v4
@@ -82,29 +84,8 @@ jobs:
 
                   echo "Successfully created packages.json (${size} bytes)"
 
-            - name: Copy site assets
-              run: |
-                  # Create a deployment directory
-                  mkdir -p deploy
-
-                  # Copy files (overwrite if exists)
-                  cp index.html deploy/
-                  cp search.js deploy/
-                  cp -R vendor deploy/
-                  # Stamp dateModified with today's date so Dataset structured data stays current
-                  sed -i "s/\"dateModified\": \"[^\"]*\"/\"dateModified\": \"$(date -u +%Y-%m-%d)\"/" deploy/index.html
-                  cp agent-access.html deploy/
-                  cp llms.txt deploy/
-                  cp packages.json deploy/
-
-                  # Create .nojekyll to prevent Jekyll processing
-                  touch deploy/.nojekyll
-
-                  # Create a simple 404 page
-                  echo '<!DOCTYPE html><html><head><meta http-equiv="refresh" content="0; url=/winget-search/"></head></html>' > deploy/404.html
-
-                  # Create a CNAME file if you're using a custom domain
-                  # echo "your-custom-domain.com" > deploy/CNAME
+            - name: Build site assets and metadata
+              run: python build_site.py --output-dir deploy
 
             - name: Deploy to GitHub Pages
               uses: peaceiris/actions-gh-pages@v4
@@ -142,4 +123,4 @@ jobs:
                   echo "- **File size**: $(stat -c%s packages.json | numfmt --to=iec-i --suffix=B)" >> $GITHUB_STEP_SUMMARY
                   echo "- **Run number**: ${{ github.run_number }}" >> $GITHUB_STEP_SUMMARY
                   echo "" >> $GITHUB_STEP_SUMMARY
-                  echo "Visit the site at: https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/" >> $GITHUB_STEP_SUMMARY
+                  python -c 'import json; print("Visit the site at: " + json.load(open("site_config.json"))["public_base_url"])' >> "$GITHUB_STEP_SUMMARY"
diff --git a/NEXT_PROMPT.md b/NEXT_PROMPT.md
@@ -1,45 +1,42 @@
 Continue work in /Users/solrevdev/Projects/winget-search.
 
-Read NEXT_STEPS.md first. It is the current agreed roadmap and work/resource log.
-IMPROVEMENTS.md contains older notes that may already be resolved.
-
-PR #7 is merged, deployed, and verified live. Its feature branch is deleted.
-Master is clean and synced. The task-owned preview servers and Playwright sessions
-from the previous round are stopped. Check the resource log and current state
-before assuming anything is still running.
-
-Keep hosting free on GitHub Pages, extraction in GitHub Actions, and search in the
-browser. Preserve the full packages.json endpoint and existing query/filter URLs.
-
-Propose the next bounded batch before implementing and wait for my agreement.
-The next chunk is to finish PR #5 and the useful remaining work in issue #1 as one
-SEO change. PR #5 now has merge conflicts with master. Inspect its diff and checks,
-resolve those conflicts, refresh its branch safely, and
-preserve feat/seo-meta-sitemap-dataset until the PR is merged or otherwise resolved.
-Update the existing PR rather than duplicating it.
-
-Use the roadmap's findings to check canonical/social metadata, preview assets,
-Dataset fields and package count, accurate sitemap dates, semantic markup, and
-accessibility. Check current primary-source guidance where needed. Coordinate the
-public-base-URL rule with issue #4's redirect work; keep the rest of issue #4 in a
-separate maintenance batch. Record Search Console work that needs an account check.
-Do not close issues until their acceptance criteria and required live checks pass.
-
-Use subagents for independent implementation or review when helpful. Give each
-clear file ownership, tell them others are working in the repo, and require them to
-report any resources they start to the parent task.
-
-After scope approval, implement and test the batch. Preserve the 38 Node and nine
-Python regressions, add meaningful checks for changed behavior, validate generated
-assets, and test affected desktop/mobile flows. Update NEXT_STEPS.md with decisions,
-results, remaining work, and the PR link. Leave the PR ready for review. Wait for
-approval before merging or deploying; after approval, verify both deployment stages
-and the live site before deleting completed branches and syncing master.
-
-Track every server, browser session, background process, and temporary preview as
-soon as it starts in NEXT_STEPS.md's resource log. Record ownership, purpose, PID or
-tool session ID, browser session name, port/URL, paths, and status. At each PR
-handoff, list what remains active and offer to tear it down in one short question.
-If cleanup is already authorized, complete it and verify the processes, ports, and
-sessions are gone. Preserve unrelated resources. Update the log and this continuation
-prompt for the next round.
+Read NEXT_STEPS.md first, then this file. SEO.md records the public URL contract,
+SEO decisions, primary sources and release checks. IMPROVEMENTS.md is historical.
+
+PR #7 is merged, deployed and verified. PR #5's conflict repair is c5de9d1.
+The user approved the SEO batch for PR #5 plus useful issue #1 work. Implementation
+and local checks are complete on feat/seo-meta-sitemap-dataset in the existing
+PR #5. Check its current head, CI and mergeability before acting.
+
+Wait for explicit merge/deployment approval. No deployment or issue closure was
+authorized for this handoff. After approval, merge and verify both Build and Deploy
+and Pages publication, then live metadata, catalog counts/dates, sitemap, preview
+image, redirect and desktop/mobile search. Preserve the feature branch until that
+verification passes; then remove it and sync master.
+
+All 38 Node tests pass. All nine Python extraction regressions plus ten build tests
+pass (19 Python total). Generated HTML/JSON-LD/XML/images and workflow checks pass.
+Search and SEO browser suites pass at 1280px and 375px. Axe light/dark page and Copy
+state checks pass after fixing contrast and keyboard access. Review NEXT_STEPS.md
+for evidence and resource status. All PR #5 servers/browser sessions are stopped;
+temporary evidence is inert. Preserve unrelated resources.
+
+Keep GitHub Pages hosting free, extraction in Actions, and search in the browser.
+Preserve packages.json and query/filter URLs. site_config.json's public_base_url
+feeds build_site.py's metadata, sitemap, guide examples and 404 destination.
+
+PR #5 includes only the shared URL/redirect portion of issue #4. Keep README,
+cache/default-branch logic and force_pages_update.sh maintenance separate. Start
+that later branch from synced master after PR #5 merges, reuse its URL rule and
+check mergeability again. Propose the next bounded batch and await agreement.
+
+Search Console still needs an account check for sitemap submission, URL indexing,
+and the old Dataset creator/license validation status. Run Rich Results Test on
+the deployed homepage. Do not close issues before their remaining criteria and
+required live checks pass.
+
+Use subagents when useful with clear file ownership; they must report resources
+to the parent. Record any server, browser, background job or preview immediately
+in NEXT_STEPS.md with owner, purpose, PID/tool session, browser name, port/URL,
+paths and status. At handoff list active resources and offer cleanup; perform any
+already-authorized cleanup and verify it. Update both handoff files each round.
diff --git a/NEXT_STEPS.md b/NEXT_STEPS.md
@@ -111,36 +111,60 @@ and search stays in the browser. The catalog endpoint and existing `?q=` links r
 SEO and deployment maintenance remain separate changes. The findings below define
 their scope; this search batch does not implement them or close their issues.
 
-### PR #5 and issue #1: one SEO change
-
-[PR #5](https://github.com/solrevdev/winget-search/pull/5) remains open at
-`949eec26e58f8f392d505a4cabba752264d3da94`. After PR #7 merged, GitHub reports
-merge conflicts with `master`; resolve them as part of the next SEO batch. Preserve
-`feat/seo-meta-sitemap-dataset` and complete the useful issue #1 work there.
-
-- Canonical and social metadata are absent from the live homepage. PR #5 supplies
-  these, including a PNG preview and its SVG source. Its description is stale:
-  it still lists the image as future work despite including it in the diff.
-- The count stamp reads the correct `metadata.total` field. Validate it against
-  the actual array length. Change `variableMeasured` from `packageId` to `id`.
-  Review the count representation: Schema.org defines `numberOfItems` for
-  [ItemList](https://schema.org/numberOfItems), not Dataset.
-- Use catalog freshness for Dataset dates and meaningful page-change dates for
-  sitemap entries. Do not stamp an unchanged agent-access page with every build's
-  date. [Google's sitemap guidance](https://developers.google.com/search/docs/crawling-indexing/sitemaps/build-sitemap)
-  calls for accurate last-modified dates and ignores priority/change frequency.
-- The homepage already has a title, description, h1, and footer. Add useful
-  header/main landmarks, result headings, and appropriate treatment of decorative
-  SVGs. This search batch adds an explicit search label. Keep the PNG's social alt
-  descriptions. Do not add
-  the issue's keyword meta tag: [Google ignores it](https://developers.google.com/search/docs/crawling-indexing/special-tags).
-- Share a single public-base-URL rule with issue #4's generated redirect. Validate
-  project paths and custom-domain paths together with canonical and sitemap URLs.
-- Validate generated HTML, JSON-LD, sitemap, and preview assets before review.
-  After an approved merge, verify both deployment stages and the live output.
-  Search Console submission and the old validation status still need a separate
-  account check. Keep issue #1 open until its remaining criteria are resolved and
-  the deployed result is verified.
+### PR #5 and issue #1: SEO ready for review
+
+[PR #5](https://github.com/solrevdev/winget-search/pull/5) remains on
+`feat/seo-meta-sitemap-dataset`. Conflict repair `c5de9d1` merged master `35bed66`
+and passed CI. The user approved the SEO scope on 2026-09-13. The implementation
+is complete and awaiting review and merge approval. Nothing has deployed from
+this batch; issues #1 and #4 remain open.
+
+- `build_site.py` replaces shell stamps with a tested static build. One explicit
+  HTTPS directory URL in `site_config.json` drives canonical/social metadata,
+  Dataset download, sitemap, guide examples, and the generated 404 destination.
+  Custom roots/subpaths and GitHub Pages user/project paths are covered. This
+  completes the redirect portion of issue #4, subject to release verification.
+- The build rejects empty/invalid catalogs and count mismatches. The preview used
+  14,836 records and `2026-09-13T18:17:57.426295Z`, matching the live download.
+  Dataset description and visible summary show the actual count; `dateModified`
+  uses extraction time. `variableMeasured` uses `id`, not `packageId`.
+- Removed Dataset `numberOfItems`, unsupported historical coverage/publication
+  dates, and the repository-as-Dataset `sameAs` claim. John Smith matches the
+  public owner profile; creator points to that profile. The MIT catalog license
+  stays and does not describe individual software licenses.
+- Sitemap dates use significant source/catalog changes, with no daily date stamp
+  for an unchanged agent page. Unknown source dates are omitted. No `priority`,
+  `changefreq`, or keywords meta tag is added. See [SEO.md](SEO.md) for primary
+  guidance, public URL rules, and Search Console follow-up.
+- Added header/main landmarks, skip links, package headings, hidden decorative
+  SVGs, stronger text/button contrast, underlined footer links, wrapped install
+  commands, and keyboard scrolling for guide code examples. The 1200 × 630 PNG
+  was regenerated from its SVG after fixing overflowing caption text.
+- All 38 Node regressions and all nine extraction tests pass, plus ten new Python
+  build tests (19 Python total). Generated homepage, agent page, and 404 pass
+  html-validate 11.15.0's HTML standard preset; JSON-LD/XML/PNG/SVG and workflow YAML
+  checks pass. Search engine, extractor, vendor assets and catalog bytes remain
+  unchanged. No required runtime service or app dependency was added.
+- Saved search and SEO browser suites pass at 1280px and 375px with no uncaught
+  exceptions. Checks cover ranking, URLs/history, filters, copy, Details, paging,
+  empty/error recovery, landmarks, metadata, static count/freshness, keyboard
+  navigation and overflow. Screenshots were inspected. Axe 4.13.0 reports zero
+  violations in eight light/dark desktop/mobile page checks and four Copy
+  hover/success checks after contrast and keyboard fixes. This is automated plus
+  keyboard review, not a claim of full assistive-technology certification.
+
+Keep this existing PR and branch. Start the later maintenance branch from synced
+master after PR #5 merges, reuse the URL rule, and recheck mergeability at every
+handoff. No separate competing SEO PR is needed. Future master edits can still
+introduce conflicts.
+
+After approval: merge, verify both Build and Deploy and Pages publication, then
+verify live metadata/counts/dates, sitemap, preview image, redirect and search.
+Only then remove the completed feature branch and sync master. Search Console
+still requires an account check: confirm sitemap submission and indexing, inspect
+both page URLs, and check the old creator/license validation status. Run Rich
+Results Test against the deployed homepage. Keep issue #1 open until the required
+live and account checks pass.
 
 ### Issue #4: deployment and documentation follow-up
 
@@ -153,8 +177,9 @@ merge conflicts with `master`; resolve them as part of the next SEO batch. Prese
 - Trial a versioned UTC daily key with prefix restore. Always run upstream
   checkout so both exact and prefix restores refresh. Remove the separate update
   step that assumes `origin/master`.
-- Generate the 404 destination using the public URL rule established with PR #5.
-  Test project paths, user-site roots, and custom domains.
+- PR #5 implements the shared URL rule and generated 404 destination, with
+  project/user-site/custom-domain tests. Reuse that builder after PR #5 merges;
+  do not reimplement or revert its redirect logic in the maintenance PR.
 - Make `force_pages_update.sh` restore the starting branch on success and failure,
   reject dirty worktrees, use fast-forward-only updates, and stage only intended
   files. Test success and fetch/push failures with temporary local Git remotes.
@@ -178,17 +203,29 @@ running resources.
 
 | Resource | Owner and location | Status |
 | --- | --- | --- |
+| Playwright `winget-seo-pr5` | PR #5 parent; PID 66266; open exec session 51766; `http://127.0.0.1:8765/winget-search/`; screenshots/logs in `.playwright-cli/` | Passed and closed 2026-09-13; PID and session checked; search suite sessions 32055 and 89714 completed |
+| SEO preview server, PID 66230 | PR #5 parent; exec session 12065; port 8765; `http://127.0.0.1:8765/winget-search/`; `/private/tmp/winget-seo-pr5-20260913/preview` | Stopped 2026-09-13; PID and port checked |
+| SEO review files | PR #5 parent; `/private/tmp/winget-seo-pr5-20260913`; catalog, generated previews, isolated validation tools/npm cache and evidence; no port or browser yet | Inert files; live catalog has 14,836 records |
+| Validation tool install | PR #5 parent; exec session 48988; `/private/tmp/winget-seo-pr5-20260913/tools` and `npm-cache`; no port/browser | Completed; axe-core 4.13.0 and html-validate 11.15.0 installed; no process remains |
 | Preview server, PID 62533 | PR #7; port 8765; `http://127.0.0.1:8765/winget-search/`; `/private/tmp/winget-preview`; exec session 32615 | Stopped 2026-09-13; port checked |
 | Staged preview server, PID 63164 | PR #7; port 8766; `http://127.0.0.1:8766/winget-search/`; `/private/tmp/winget-review-preview`; exec session 57935 | Stopped 2026-09-13; port checked |
 | Playwright `winget-search` | PR #7 desktop/mobile-width checks | Closed 2026-09-13 |
 | Playwright `winget-mobile` | PR #7 touch checks | Closed 2026-09-13 |
 | Playwright `winget-release-check`, PID 63851 | PR #7 public deployment verification; `https://solrevdev.com/winget-search/`; no local server | Passed and closed 2026-09-13; PID checked |
 
 Preview directories and `.playwright-cli/` screenshots/logs are inert evidence.
+PR #5 also retains JSON test results and isolated validation tools under
+`/private/tmp/winget-seo-pr5-20260913`. All PR #5 task resources are stopped;
+no active browser, preview server or background test remains.
 No task-owned servers or Playwright sessions remain active. Verified with
 `playwright-cli list`, process checks, and listener checks on ports 8765 and 8766.
 Unrelated services were left running.
 
+PR #5 conflict repair (2026-09-13): no servers, browser sessions, background
+processes, or temporary previews started. The read-only SEO scope subagent owns
+review findings only and reports any resources to the parent. Its review is complete. Build and markup subagents started no servers or
+browsers; their Python test fixture directories were cleaned automatically.
+
 ## Following batches
 
 1. **Install-list builder.** Select multiple packages, keep selections in local