fix(seo): Wave 1 — fix critical SEO gaps

- Fix duplicate faq/ruFaq keys in dice.json, list.json, colors.json - Add <main> landmarks to about/privacy pages (EN + RU) - Move YandexRTB after <main> on homepage - Add x-default hreflang to BaseLayout - Configure sitemap i18n with hreflang alternates - Add Open Graph + Twitter Card meta tags - Create default OG image (1200x630)
2026-05-14 02:39:56 +03:00
parent 75038780d5
commit 43ea9bc8f3
23 changed files with 2087 additions and 146 deletions
@@ -0,0 +1,200 @@
+# Create AGENTS.md
+
+## TL;DR
+
+> Create `AGENTS.md` at repo root with compact, high-signal instructions for future OpenCode sessions. Replace stale `CLAUDE.md` claims. Verify all facts from executable sources.
+> 
+> **Deliverables**: `AGENTS.md` (new file), committed and pushed to `main`
+> 
+> **Estimated Effort**: Quick
+> **Parallel Execution**: NO — single task
+> **Critical Path**: Task 1 only
+
+---
+
+## Context
+
+### Original Request
+User: "обнови Agents.md" (Create or update `AGENTS.md` for this repository).
+
+### Key Facts Discovered
+- **Project**: Astro 4 + Tailwind CSS 4 static site, 28 random-value generators (bilingual EN/RU)
+- **Deploy**: GitHub Actions + rsync to reg.ru on push to `main`
+- **CI gate order**: `npm ci` → `npm run lint` → `npm run test` → `npm run build` → `rsync`
+- **i18n**: Astro built-in routing, `defaultLocale: "en"`, `prefixDefaultLocale: false`. EN at `src/pages/`, RU at `src/pages/ru/`. Locale derived from `Astro.currentLocale`.
+- **CRITICAL quirk**: Never use shared dynamic `[slug].astro` for RU pages — Astro bundles all imported component scripts, causing every RU page to run all 28 generator scripts.
+- **Generators**: 28 live. Each requires 4 files: content JSON (EN+RU fields), component, EN page, RU page.
+- **Content schema**: Zod `.strict()` in `src/lib/generator-schema.ts` — unknown fields fail build.
+- **Shared utilities**: `src/lib/client/random.ts` (crypto `getRandomValues`), `src/lib/client/i18n.ts` (client locale helpers). All 28 generators refactored to use these (zero `Math.random`).
+- **Dice engine**: deduplicated into `src/lib/dice-engine.ts`, imported by `DiceGenerator.astro`.
+- **Test runner**: Vitest v4, `environment: "node"`, `include: ["src/**/*.test.ts"]`.
+- **Lint**: ESLint via `eslint.config.mjs`, ignores `dist/`, `.astro/`, `node_modules/`, `src/env.d.ts`.
+- **CLAUDE.md is stale**: claims "10 generators" and "No test runner or linter is configured" — both false.
+- **No existing agent instruction files**: no `.cursorrules`, `.cursor/rules/`, `.github/copilot-instructions.md`, `opencode.json`.
+
+### Metis Review
+- No gaps identified — repo answers all important questions.
+
+---
+
+## Work Objectives
+
+### Core Objective
+Write a compact `AGENTS.md` at repo root containing only high-signal, repo-specific guidance that future OpenCode agents would likely miss.
+
+### Concrete Deliverables
+- `AGENTS.md` file at repo root
+
+### Definition of Done
+- [ ] `AGENTS.md` exists at repo root
+- [ ] `npm run lint` passes (0 errors)
+- [ ] `npm run build` passes (62 pages)
+
+### Must Have
+- Exact developer commands
+- CI gate order
+- i18n routing quirks and the `[slug].astro` prohibition
+- Generator addition workflow (4 steps)
+- Zod strict schema warning
+- Shared utilities architecture (random.ts, i18n.ts, dice-engine.ts)
+- Stale CLAUDE.md warnings
+
+### Must NOT Have
+- Generic software advice
+- Long tutorials or exhaustive file trees
+- Obvious language conventions
+- Speculative claims
+
+---
+
+## Verification Strategy
+
+### Test Decision
+- **Infrastructure exists**: YES
+- **Automated tests**: NO (not needed for doc file)
+- **Agent-Executed QA**: YES — verify lint and build pass after file creation
+
+### QA Policy
+Every task MUST include agent-executed QA scenarios.
+
+---
+
+## Execution Strategy
+
+### Wave 1 (Single Task)
+
+- **Task 1**: Write `AGENTS.md`
+
+---
+
+## TODOs
+
+- [ ] 1. Write AGENTS.md
+
+  **What to do**:
+  - Create `/home/emil/Desktop/Coding/AI/Randify.pro/AGENTS.md` with the following verified content:
+    - Project overview (28 generators, Astro 4 + Tailwind 4)
+    - Developer commands (exact npm scripts)
+    - CI gate order
+    - i18n routing architecture and `[slug].astro` prohibition
+    - Path alias `@/* → src/*`
+    - Shared utilities table (random.ts, i18n.ts, dice-engine.ts)
+    - Shared components (ResultBox.astro, CopyButton.astro)
+    - Adding a generator: 4-step workflow
+    - Key conventions (accent color, icons, analytics IDs)
+    - Stale CLAUDE.md warnings
+    - Testing, lint & format notes
+    - Build artifacts and operational gotchas
+  - Use compact bullets, not prose paragraphs.
+  - Verify no generic advice included.
+
+  **Must NOT do**:
+  - Do NOT include generic software advice
+  - Do NOT write long tutorials
+  - Do NOT include obvious conventions
+  - Do NOT make speculative claims
+  - Do NOT touch `CLAUDE.md` (leave it as-is; AGENTS.md is the new source of truth)
+
+  **Recommended Agent Profile**:
+  - **Category**: `quick`
+  - **Skills**: []
+
+  **Parallelization**:
+  - **Can Run In Parallel**: NO
+  - **Parallel Group**: Sequential
+  - **Blocks**: None
+  - **Blocked By**: None
+
+  **References**:
+  - `CLAUDE.md` — existing guidance (partially stale, use for comparison only)
+  - `package.json` — exact npm scripts
+  - `astro.config.mjs` — i18n routing config
+  - `vitest.config.ts` — test config
+  - `eslint.config.mjs` — lint rules and ignores
+  - `.github/workflows/deploy.yml` — CI gate order
+  - `src/lib/generator-schema.ts` — Zod strict schema
+  - `src/lib/client/random.ts` — crypto random utility
+  - `src/lib/client/i18n.ts` — client i18n helper
+  - `src/lib/dice-engine.ts` — canonical dice engine
+
+  **Acceptance Criteria**:
+  - [ ] `AGENTS.md` exists at `/home/emil/Desktop/Coding/AI/Randify.pro/AGENTS.md`
+  - [ ] `npm run lint` → PASS (0 errors)
+  - [ ] `npm run build` → PASS (62 pages generated)
+
+  **QA Scenarios**:
+
+  ```
+  Scenario: File created and lint passes
+    Tool: Bash
+    Preconditions: None
+    Steps:
+      1. Read AGENTS.md and verify it contains: "28 random-value generators", "CI gate order", "[slug].astro" warning, "Zod .strict()" warning, shared utilities table
+      2. Run: npm run lint
+      3. Assert: 0 errors
+    Expected Result: lint exits 0, no errors
+    Evidence: .sisyphus/evidence/agents-lint.txt
+
+  Scenario: Build passes after file creation
+    Tool: Bash
+    Preconditions: None
+    Steps:
+      1. Run: npm run build
+      2. Assert: "62 pages" in output, exit code 0
+    Expected Result: 62 pages generated, exit code 0
+    Evidence: .sisyphus/evidence/agents-build.txt
+  ```
+
+  **Evidence to Capture**:
+  - [ ] `.sisyphus/evidence/agents-lint.txt`
+  - [ ] `.sisyphus/evidence/agents-build.txt`
+
+  **Commit**: YES
+  - Message: `docs: add AGENTS.md with high-signal repo guidance`
+  - Files: `AGENTS.md`
+  - Pre-commit: `npm run lint && npm run build`
+
+---
+
+## Commit Strategy
+
+- **1**: `docs: add AGENTS.md with high-signal repo guidance` — AGENTS.md, npm run lint && npm run build
+
+---
+
+## Success Criteria
+
+### Verification Commands
+```bash
+npm run lint   # Expected: 0 errors
+npm run build  # Expected: 62 pages
+```
+
+### Final Checklist
+- [ ] AGENTS.md exists at repo root
+- [ ] Contains 28 generators count (not 10)
+- [ ] Contains exact CI gate order
+- [ ] Contains [slug].astro prohibition
+- [ ] Contains Zod strict warning
+- [ ] Lint passes
+- [ ] Build passes