feat: /ai v2, how I implement AI

[romahawk]

What and why

/ai is rebuilt as "How I implement AI" for hiring teams. It has one call to action (Download CV), three working rules with a diagram, two proof cards (Rolevoice, my personal agent operating system), and the field notes and glossary folded into native <details>. The page is shorter (3,549px at 1366, 5,168px at 390), every piece of text is still indexable and deep-linkable, and the identity matches the CV ("Technical Project Manager / Implementation Lead"). Copy is word for word from the brief's Copy section; decisions A1 to A8 are applied as written.

Closes #

Changes

Before / after copy

Where	Before	After
Meta title	AI Field Guide: Harness, Skills, Memory, Tools, Cost	How I implement AI | Roman Mazuryk, Technical Project Manager / Implementation Lead
Meta description	A practical reference for building with AI agents: terminology, best practices and tool choices, applied to real projects by Roman Mazuryk.	How a Technical Project Manager with 20+ years in regulated MedTech, pharma and logistics uses AI every day: one source of truth, approval gates, checks before anything ships. Hamburg area, open to remote across the EU.
OG / Twitter title	AI Field Guide: Harness, Skills, Memory, Tools, Cost	How I implement AI · Roman Mazuryk
Hero eyebrow	AI Field Guide · Last reviewed 30 Sep 2026	AI in practice · Updated Oct 2026
Hero H1	I help organisations move AI from pilot to everyday use, safely.	How I implement AI
Hero subline	20+ years delivering software in regulated MedTech, pharma and logistics. This page shows how I build and run AI workflows in practice.	I run AI work the way I run regulated rollouts. One source of truth, clear approvals, and nothing ships without a check.
Hero actions	3 proof points, Download CV + Email me buttons, section index	Download CV (primary, download) + text link "See my implementation work" → /#work
Closing title	Hiring a Technical PM or AI Implementation Lead?	Hiring a Technical Project Manager / Implementation Lead who already works with AI every day?
Closing actions	"Here's my CV, or email …" + "Building an AI product or pilot? Happy to compare notes."	Download CV (primary) + text link romazuryk@gmail.com

New sections: How I work (#principles: 3 rules, inline SVG diagram, visible caption), Proof (#proof: Rolevoice, "Deployed, pre-pilot"; personal agent operating system, "Running daily"), Field notes (#notes), Glossary (#glossary), Contact (#contact).

Removed

• The "> " heading prefix
• The engine/car metaphor paragraph (kbMeta.mentalModel)
• Per-pillar accent colours
• The 5-card pillar navigator
• The Magic Kick "Public proof" box, its GitHub and live-app links, and kbPublicProof
• Two of the three Magic Kick field-note rows. One unlinked line remains, and Magic Kick is left out of the matrix (A3)
• The hero proof-points list (including "20+ multi-vendor …") and the hero Email button
• "In use" / verdict pills everywhere; verdicts are now plain text
• The reveal fade on everything except the hero
• The 1360px-only left rail and the section index on /ai (/services keeps both)
• "Happy to compare notes"
• "Last reviewed"
• The glossary pillar filter tabs; search stays
• Tool rows that need explaining: superpowers, ponytail, ECC / gstack, ui-ux-pro-max, taste-skill, wshobson/agents, planning-with-files, graphify / codegraph, firecrawl, multica / vibe-kanban, cc-switch / claude-code-router, codex-plugin-cc, caveman. Three tools per pillar remain

Code

• src/data/aiKnowledgeBase.js:
  • new kbMeta, kbHero, kbClosing, kbSectionNav
  • new kbPrinciples, kbProof, kbNotes, kbGlossaryCopy, kbMaintenance (all page copy now lives in data)
  • principle per pillar
  • learning-product → rolevoice ("Rolevoice", "M.Sc. capstone, first pilot: German", "Deployed, pre-pilot")
  • unused icon / tagline fields removed
• src/components/KnowledgeBasePage.jsx:
  • rebuilt in the order Hero → chip strip → How I work → Proof → Field notes (5 × <details name="pillar"> + matrix <details>) → Glossary <details> → maintenance note → closing band
  • deep links open the target <details> on load and on hashchange
• src/components/common/SectionNav.jsx: new SectionChips component.
  • Where scroll-target-group is supported, :target-current drives the active chip and aria-current is synced on scrollend
  • Elsewhere the existing useActiveSection IntersectionObserver sets the active chip
  • /services rail and index unchanged
• src/assets/css/knowledge-base.css:
  • rewritten to the Visual spec type scale and spacing
  • the chip strip is sticky from 768px, with a hairline via @container scroll-state(stuck: top)
  • 44px tap targets; buttons full width under 480px
  • content-visibility: auto + contain-intrinsic-size on #notes and #glossary
• ai/index.html, src/hooks/useOgMeta.js: Copy meta. applyMeta gets an optional ogTitle for the shorter OG/Twitter title
• scripts/check-consistency.mjs: bans "AI Implementation Lead", "20+ multi-vendor", "Happy to compare notes", "AI learning product", "learning-product"; BANNED_EXACT adds "teacher accepts". All existing entries are kept
• src/assets/css/footer.css: the Consulting link uses --muted-strong. It was 4.47:1 on the light footer, which was the only Lighthouse accessibility failure (see Notes)
• public/sitemap.xml: unchanged

Grep counts (src/ + ai/index.html, case-insensitive), before → after:

Term	Before	After
AI Implementation Lead	1	0
20+ multi-vendor	1	0
teacher	0	0
DeutschOn	0	0
AI learning product	1	0
learning-product	5	0
Magic Kick	2 (+2 links)	3 in source (2 code comments + the project entry); 1 rendered, unlinked, in the Harness field-notes row
Happy to compare notes	1	0
Last reviewed	1	0

Verification

• npm run lint exits 0
• npm run build exits 0 (guard: check-consistency: 61 files clean)
• CI green on this PR (CI + Lighthouse CI): pending at the time of writing
• Vercel preview opened and checked, not just localhost: not done

Local checks used npm run preview with headless Edge 155 over CDP, at 1366×768 and 390×844, in dark and light (localStorage.theme):

Check	1366	390
Page height, all rows closed (target 6,000 / 8,000)	3,549px	5,168px
Page height with Memory open	4,887px	7,756px
Horizontal page scroll	none	none
Chip strip	sticky at top: 72px (header height); active chip follows Principles, Proof, Field notes, Contact	static (no sticky on mobile); active chip follows
<details> keyboard (Enter opens, Space closes, all 7)	7/7	7/7
Exclusive pillar rows (open Harness, then Memory)	only Memory open	only Memory open
/ai#memory on load	Memory open, top at 136px (under header + strip), no other row open	Memory open, top at 72px
hashchange to #tools	Tools open, Memory closed	same
Diagram	horizontal SVG, 105px high, role="img", aria-label = caption; accent node fill matches theme	vertical SVG, role="img", same label
Tap targets < 44px	14 total: 13 in the shared header/footer (unchanged by brief) + the site-wide skip link (198×40). 0 on the /ai page content	same
Download CV	/roman-mazuryk-cv.pdf with download; served as application/pdf, 105,702 bytes (the Oct 2026 CV)	same
Email link	mailto:romazuryk@gmail.com	same
Tab order across content-visibility sections	chips → 5 field-note summaries → matrix → glossary → Download CV → email → footer, in order	same
Glossary	8 terms shown, 23 hidden="until-found"; search "token" shows the 1 match; "Show all 31 terms" shows all	same
Reveal class outside the hero	0	0
Em dashes in rendered text (textContent, all rows open)	none	none
Console	only 404 /_vercel/insights/script.js (Vercel Analytics, local preview only)	same

Lighthouse 12 (local preview, Edge, light theme):

Run	Perf	A11y	BP	SEO	LCP
Mobile, before contrast fix	93	96	96	100	2.82s
Mobile, final	86	100	96	100	2.94s
Desktop, final	99	100	96	100	0.80s
Live main /ai, mobile (baseline)	85	96	n/a	100	3.15s

The mobile Perf target (≥ 95) and LCP target (< 2.5s) are not met locally. In every run, including the live baseline, about 2.4s of LCP is render delay: the SPA waits for main.js and the lazy page chunk before it paints text. FCP on the branch is about 1s faster than live (1.7 to 1.9s vs 2.9s). Mobile Perf also swings 86 to 93 between identical runs. Best Practices 96 is the Analytics 404, which only happens locally.

How to test

1. Open the Vercel preview from the checks below and go to /ai
2. Hero: one Download CV button and the "See my implementation work" link (→ /#work)
3. From 768px wide, scroll: the chip strip sticks under the header and the active chip follows the section. On Chrome 140+ a hairline appears while stuck
4. Field notes: open Harness, then Memory; Harness closes. Use Tab + Enter/Space on a row summary
5. Load /ai#memory directly: the Memory row is open and in view
6. Glossary: open it, search "token", clear it, then click "Show all 31 terms". Ctrl+F for "Plugin" should reveal a hidden term (Chrome/Edge/Firefox 148+)
7. Closing band: Download CV gets the Oct 2026 PDF; the email link opens a mail client
8. Repeat at 390px in dark and light

Core loop: home → Work → /ai → Download CV still works.

Not tested:

• The Vercel preview itself
• Real iOS Safari or Android Chrome (only emulated 390px in Edge)
• Firefox and Safari, where :target-current, scroll-state queries and (on Safari) hidden="until-found" fall back
• Ctrl+F find-in-page reveal (only the attribute and the fallback paths were checked)
• A screen reader
• Lighthouse on Vercel (left to Lighthouse CI)

Quality gates

• Mobile checked (390px emulated viewport)
• No console errors in the preview: local preview only; the one error is the Vercel Analytics 404
• Accessibility kept: landmarks, aria-label on the diagram and matrix region, focus-visible on summaries, chips and links, prefers-reduced-motion block kept. Lighthouse A11y 100
• No new npm dependency (Lighthouse was run via npx, not added to the project)
• Lucide icons use named imports (ArrowUpRight, ChevronDown, FileDown, Search); the unused icon map was removed
• Redirects in vercel.json: /ai route and ai/index.html entry unchanged

Docs

• CHANGELOG.md updated under [Unreleased]
• docs/ / CLAUDE.md: no routing or architecture change

Screenshots

Captured locally at 1366px and 390px, in dark and light:

• hero
• proof cards
• Memory row open
• glossary open

The GitHub CLI can't upload images, so Roman needs to drag them in from the session scratchpad, or use the Vercel preview.

Notes for review

• Footer change. The brief says the footer stays identical. The only change is the Consulting link colour (--muted → --muted-strong), to fix the AA failure feat: homepage v3, TPM / Implementation Lead #121 introduced on every page. It was the only Lighthouse accessibility failure.

• Agent-OS skills row (A2). "…reused across Claude apps…" became "…reused…", so no tool name sits next to the personal agent operating system. The proof card follows A2 exactly.

• Magic Kick (A3). Exactly one line: the Harness row "An issue-to-PR workflow…". The ADR and AI-routes rows are removed, and Magic Kick is left out of the matrix (matrix: false) so it doesn't appear a second time.

• Tool choice. Three per pillar, keeping names that describe themselves:

  • Harness: Claude Code, learn-claude-code, andrej-karpathy-skills
  • Skills: anthropics/skills, claude-plugins-official, awesome-claude-skills
  • Memory: CLAUDE.md, repomix, claude-mem
  • Tools: playwright-mcp, gh CLI / github-mcp, awesome-mcp-servers
  • Cost: claude-hud, claude-code-best-practice, system-prompts-and-models-of-ai-tools

  Harness, Skills, Tools and Cost don't have one of each verdict, because the remaining candidates needed explaining. Roman may want different picks.

• UI labels not in the Copy section. Section-internal headings were moved into data unchanged ("Terms", "Best practices", "Pitfalls", "In my projects", "Tools: use, try, skip"). The glossary's "Show all 31 terms" button is new; without it, 23 terms would only be reachable through search or find-in-page.

• "Glossary: 31 terms in one line" is built from kbGlossary.length, so it stays accurate if terms change.

• Glossary pillar labels are plain text now, not links (they were small, under-44px links).

• OG image alt changed from "AI Field Guide by Roman Mazuryk." to "How I implement AI, by Roman Mazuryk.". This wasn't in the Copy section, but the old name is retired.

• Maintenance paragraph is kept as written. It still defines In use / In build / Pre-beta, but those labels now only appear as plain text in the mobile matrix cards.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
portfolio-fullstack	Ready	Preview	Oct 15, 2026 6:27am UTC
portfolio-react	Ready	Preview	Oct 15, 2026 6:27am UTC

[romahawk]

Discarded at Roman's request; not merging.