Imported from elng12/pinpointanswertoday.app (AGENTS.md). Install upstream with npx skills add elng12/pinpointanswertoday.app. Copyright stays with the author.

Repository Guidelines

Communication Style

• Default to plain Chinese in user-facing messages.
• Start with the conclusion, then explain impact, then the action taken or next step.
• Avoid unexplained jargon. When a technical term is necessary, explain it in plain language the first time it appears.
• Do not rely on raw log text, status codes, or CLI flags alone; translate them into what they mean for the user.
• Keep updates readable for non-engineers unless the user explicitly asks for technical detail.

Project Structure & Module Organization

Source lives under src/: src/app hosts Next.js App Router pages plus API routes (see /app/api/* for admin proxies), while src/lib provides shared Prisma, logging, validation, and ISR helpers. Persistent schema and seeds are in prisma/. Operational tooling is split between scripts/ (TypeScript utilities, SEO checks, cache probes), automation-script/ (OpenAI-driven publisher), and tools/ (manual HTML helpers). Static assets sit in public/（含 admin/publisher-legacy.html 备份），官方后台入口为 /admin/publisher，测试文件位于 src/lib/__tests__ 与 tests/。

Build, Test, and Development Commands

• npm run dev: start the Next.js dev server on port 3003.
• npm run build / npm run start: production build and serve.
• npm run lint / npm run typecheck: ESLint (with @typescript-eslint, eslint-config-next) and strict TypeScript.
• npm run test: Node’s --test runner (imports via tsx) for unit suites in src/lib/__tests__.
• npm run test:e2e: Playwright smoke tests.
• npm run check:entry and npm run seo:scan: synthetic entry checks and link crawling; CI relies on these outputs for discoverability reports.

Coding Style & Naming Conventions

Use TypeScript with 2-space indentation, camelCase for functions/variables, and PascalCase for React components. Favor module-scoped helpers (e.g., getPuzzleDetailPath) over inline literals to keep DRY between middleware, admin tools, and API routes. Tailwind is used sparingly inside src/components. Run npm run lint before opening a PR; Prettier is implicit through ESLint’s formatting rules.

Testing Guidelines

Unit files mirror subjects (*.test.ts next to the module in src/lib). Name tests after observable behavior (revalidate-targets.test.ts). When touching automation or publishing, add Playwright coverage (tests/) and expand scripts/check-entry.ts fixtures if redirects or cache behavior changes. CI expects npm run lint && npm run test to pass locally; include fixtures or mocks so tests do not hit real LinkedIn endpoints.

Commit & Pull Request Guidelines

History follows short, scoped prefixes like fix(home): … or seo(sitemap): …. Keep messages imperative and mention surface area (publish-proxy, middleware). PRs should link the relevant doc/issue, list testing commands, screenshot UI changes (admin tools, puzzles), and disclose any new env vars (ADMIN_PASSPHRASE, INDEXNOW_*). Coordinate cache or automation changes with deployment docs (docs/deployment-hand-off.md) so reviewers can trace risk.

Security & Configuration Tips

Secrets come from .env/GitHub Actions — never hardcode tokens. Admin flows require X-Admin-Pass and REVALIDATE_SECRET; verify /api/admin/health before使用 /admin/publisher（或 legacy 备份）操作。When adding routes, whitelist sitemap/feed paths in middleware.ts and mirror cache-tag sets with triggerCacheRevalidation to preserve ISR guarantees.