Imported from ByShahbazi/Portfolio (AGENTS.md). Install upstream with npx skills add ByShahbazi/Portfolio. Copyright stays with the author.

Agent Guide — Shahbazi Portfolio

This file is the source of truth for AI agents working on this repo. Read it before editing. Prefer small, local changes that match existing patterns.

Product

• Personal portfolio for Mohammad Mahdi Shahbazi (محمدمهدی شهبازی), QA Automation Engineer.
• Audience: recruiters / hiring managers scanning dark, mono, emerald engineering aesthetic.
• Live site: https://byshahbazi.github.io/Portfolio/ (base: '/Portfolio/').

Stack

Hard constraints (do not violate)

1. Do not push unless the user explicitly asks.
2. Do not commit unless the user explicitly asks.
3. Keep visual language: near-black #050505, emerald accents, mono type. Avoid AI-slop purple/cream/broadsheet looks.
4. GitHub Pages is static: production must work with FALLBACK_CONTENT (no API).
5. vite.config.ts base must stay '/Portfolio/'.
6. Persian user replies → wrap prose in <div dir="rtl">…</div>.
7. Prefer editing existing files over adding parallel systems.

Architecture (mental model)

index.html → index.tsx → App.tsx
  ├── Navbar
  ├── Hero                    (desktop resume + code scroll cue)
  ├── ResumeGate              (non-desktop resume + code scroll cue)
  ├── About
  ├── Skills (+ SkillModal, SkillIcon)
  ├── Projects
  ├── Experience
  └── Contact
data: portfolio-data.js ← constants.FALLBACK_CONTENT ← App validation
styles: index.css (utility-ish custom CSS, not Tailwind build)

Where to change what

Responsive rules

• Breakpoint desktop = min-width: 1024px.
• Below 1024px: hide .hero-actions--desktop, show .resume-gate centered above About.
• Skills: 1-col list rows on small screens; multi-col cards from 640px+.
• Always respect prefers-reduced-motion.

Content / validation

• App.tsx validates API payloads with isContent / isSkill / isProject.
• If you add fields to data, update types.ts and validators and portfolio-data.js.
• Resume file: public/Resume-Shahbazi.pdf → URL via getResumeUrl().

Design taste (portfolio)

• One job per section; avoid card spam in heroes.
• Motion: purposeful (typewriter, scroll cue, reveals), not decorative noise.
• Skills rings use CSS vars --ring-size, --ring-core, --ring-icon.
• Brand skill icons should stay recognizable official marks (>90%), not generic Lucide substitutes.

Commands

npm install
npm run dev          # Vite + Express
npm run typecheck
npm run build
npm run preview      # serves /Portfolio/ base

Deploy checklist (human)

1. Pages source = GitHub Actions (not branch root).
2. Push main only when asked.
3. Confirm built assets load (/Portfolio/assets/*.js), not raw index.tsx.

Doc map for agents

• docs/agent-overview.md — workflow + file map
• docs/components.md — every React component
• docs/data-and-types.md — data contract
• docs/styles.md — CSS conventions
• docs/skills.md — Skills section + icons
• docs/about.md
• docs/projects.md
• docs/experience.md
• docs/education.md
• docs/contact.md
• docs/seo.md
• docs/deploy.md

Definition of done (agent)

• npm run typecheck / npm run build pass when UI/data changed.
• Mobile + desktop both checked for the touched section.
• No secrets committed.
• Docs updated if behavior/contract changed.