site: regenerate from static-tool-page-template

[plx]

Summary

• Rebuilds the Astro/Starlight site on the static-tool-page-template baseline: project metadata is centralized in src/site.config.mjs, the per-module *.components.css files are replaced by a generated theme.css plus a rewritten landing.css, and docs pages move from .md to .mdx.
• Adds site tooling: Playwright + axe tests, cspell, Prettier, tsconfig.json, justfile, env.d.ts, favicon/tool-mark assets, and a stock site README.md.
• Splits the single pages.yml workflow into a site-check.yml PR validator (format, spell, typecheck, build, Playwright) and a site-publish.yml deploy workflow, both scoped to site/** paths.
• Refreshes AGENTIC_NAVIGATION_GUIDE.md to match the new site/ tree.

Test plan

• site-check workflow passes on the PR
• site-publish deploys cleanly on merge to main

🤖 Generated with Claude Code

[claude]

Code Review

Overview

This PR rebuilds the site/ tree from a static-tool-page-template baseline. The structural wins are real: project metadata is centralized in site.config.mjs, the old multi-file design-system CSS is replaced by a flatter theme.css + landing.css, docs pages gain .mdx extensions, and a new CI pair (site-check.yml / site-publish.yml) replaces the monolithic pages.yml. The addition of Playwright+axe tests, cspell, Prettier, and a justfile rounds out the tooling story. Overall a solid regeneration. A few things worth addressing before merging:

---

Issues

Security — action pins regressed to floating tags

The deleted pages.yml used immutable SHA pins for every third-party action:

uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4.3.1

Both new workflows use floating version tags:

uses: actions/checkout@v5
uses: actions/setup-node@v5

Floating tags can be moved by an account compromise or a force-push. Consider pinning to SHAs as the old workflow did — or at minimum add a comment explaining the deliberate policy change (e.g. Dependabot will keep them updated).

---

Performance — npm cache dropped from CI

The old pages.yml had:

- uses: actions/setup-node@...
  with:
    node-version: 22
    cache: npm
    cache-dependency-path: site/package-lock.json

Neither site-check.yml nor site-publish.yml include cache: npm. With the new devDependencies (Playwright, axe, cspell, Prettier, TypeScript) the install step will be noticeably heavier on every run. Adding the cache key back is a one-liner.

---

Maintainability — basePath duplicated across three files

/agentic-navigation-guide is defined independently in three places:

File	Line
site/src/site.config.mjs	"basePath": "/agentic-navigation-guide"
site/playwright.config.ts	const basePath: string = "/agentic-navigation-guide"
site/tests/site.spec.ts	const basePath: string = "/agentic-navigation-guide"

If the deploy path changes, all three need to be updated in sync. playwright.config.ts and site.spec.ts could import from site.config.mjs:

import { siteConfig } from "../src/site.config.mjs";
const basePath = siteConfig.site.basePath;

The same applies to projectTitle and projectDescription in site.spec.ts — they are copied verbatim from siteConfig.project.*.

---

Minor observations

• docs.sidebar ↔ docs.pages data duplication in site.config.mjs: these two arrays overlap on title/slug for the same four pages. A future addition would require touching both. Not a blocker, but worth a note in a comment that they must stay in sync.

• package.json semver floor lowered: @astrojs/starlight drops from ^0.39.2 → ^0.39.0 and astro from ^6.3.1 → ^6.0.0. The lock file pins actual resolved versions so this won't cause a runtime change today, but it's a wider allowable window. Likely intentional for template compatibility.

• Missing astro script alias: the old package.json had "astro": "astro" as a shorthand; the new one doesn't. Minor, but npx astro ... still works.

---

What's well done

• Accessibility improvements: skip-to-content link, aria-controls="mobile-nav", aria-expanded toggling, and Escape-key close for mobile nav are all implemented correctly.
• The landing.ts copy-button handler correctly clears the reset timer before starting a new one, avoiding race conditions.
• tsconfig.json with astro/tsconfigs/strict + checkJs: true gives good coverage of the .mjs config file.
• The Playwright test suite is thorough: viewport overflow, link validity (including hash-target existence), and axe audits on key pages.
• The site-check.yml / site-publish.yml split is a clean separation of concerns.

🤖 Generated with Claude Code

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 995abe8d40

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Raise the advertised Node floor to 22.12

For local or engine-strict installs on Node 22.0–22.11, this package now advertises support even though the committed lock resolves astro@6.3.1, whose own engines entry requires node >=22.12.0; those environments can fail npm ci/build despite satisfying this top-level constraint. Please align this to >=22.12.0 so contributors and tooling reject unsupported Node versions up front.

Useful? React with 👍 / 👎.

[claude]

Code Review

Overview

This PR regenerates the Astro/Starlight site from a static-tool-page-template baseline. The main changes are:

• Project metadata centralized in src/site.config.mjs (consumed by Astro config, Playwright config, and the test suite)
• CSS refactored: per-module *.components.css files → a leaner theme.css + rewritten landing.css
• Docs pages renamed from .md to .mdx
• New tooling: Playwright + axe-core, cspell, Prettier, tsconfig.json, justfile
• Workflows split: pages.yml → site-check.yml (PR validator) + site-publish.yml (deploy-only)
• AGENTIC_NAVIGATION_GUIDE.md updated to reflect the new site/ tree

The overall direction is good — separating CI concerns, adding accessibility testing, and centralizing site config are all meaningful improvements.

---

Issues

Dead branch in both CI workflows

In site-check.yml and site-publish.yml, the install step is:

run: |
  if [ -f package-lock.json ]; then
    npm ci
  else
    npm install
  fi

package-lock.json is committed to the repo, so the else branch is unreachable. Just use npm ci directly. The conditional adds noise without benefit.

Missing prettier-plugin-astro

prettier is listed as a dev dependency, and npm run format:check runs prettier --check .. Without prettier-plugin-astro, Prettier has no built-in parser for .astro files and will silently skip them (or warn, depending on version). This means .astro formatting is not actually enforced in CI. Either add prettier-plugin-astro as a dev dependency with a matching .prettierrc config, or explicitly scope the format check to non-Astro files.

Dependency version ranges downgraded

"@astrojs/starlight": "^0.39.0"  // was ^0.39.2
"astro": "^6.0.0"                // was ^6.3.1

The lock file pins the actual versions, so this won't matter day-to-day, but the declared ranges now allow older patch releases that the project apparently wasn't using before. If the downgrade is intentional to match the template baseline, a comment explaining the decision would help.

---

Minor Notes

site.config.mjs "Generated" comment is slightly misleading

// Generated by static-tool-page-template. Edit this file and docs content before changing
// stock landing page components.

The file is both generated and the canonical source of truth going forward. The comment direction ("edit this file … before changing stock components") is correct, but "Generated" implies it can be regenerated and overwritten. Consider rewording to make clear this file owns project configuration.

typescript: ^6.0.0 — TypeScript 6 is the cutting edge. If any transitive tooling has stricter TS4/5 compatibility requirements this range is fine (npm resolves semver), but it's worth confirming the @astrojs/check peer dep is happy with TS6 in practice.

Playwright audit scope (pagesToAudit) only runs axe on the landing page and first docs page. That's a reasonable starting point, but noting it's not exhaustive.

---

What's Good

• Splitting pages.yml into separate check and publish workflows is the right separation of concerns. The check workflow correctly scopes to pull_request triggers and the publish workflow is deploy-only.
• siteConfig as the single source of truth shared across astro.config.mjs, playwright.config.ts, and site.spec.ts is clean — no config drift possible between the test runner and the actual site.
• The Playwright test suite is thorough: viewport overflow checks, accessible mobile nav state (ARIA attributes + keyboard Escape), link validation (status + hash anchor existence), and axe accessibility audits across three device classes.
• SITE_TEST_PORT escape hatch in the Playwright config is a nice DX touch.
• The accessibility additions (skip-link, sr-only, proper aria-controls/aria-expanded on the mobile toggle) are well-implemented.
• The navigation guide (AGENTIC_NAVIGATION_GUIDE.md) is correctly updated in the same PR — consistent with the project's own self-validation principle.
• Action SHAs are pinned with version comments throughout — good supply-chain hygiene.