Imported from ai-shifu/ai-shifu (src/web/src/lib/AGENTS.md). Install upstream with npx skills add ai-shifu/ai-shifu --skill lib. Copyright stays with the author.

Cook Web Domain: lib

This file adds local guidance for src/web/src/lib. Read the repository root and src/web/AGENTS.md first, then use this file for domain-specific frontend ownership.

Scope

• This domain owns shared frontend infrastructure such as request handling, generated API wrappers, i18n helpers, normalization, and testable utility code.

• Representative files in this subtree: src/web/src/lib/request.ts, src/web/src/lib/api.ts, src/web/src/lib/shifu-normalize.ts, src/web/src/lib/unified-i18n-backend.ts

• Keep durable frontend rules here only when they are more specific than the Cook Web-wide guidance in the parent directory.

• Use focused frontend verification around src/web/src/lib/ before widening to global type and lint checks.

Do

• Start from the local entry files and preserve how lib currently separates route code, shared logic, state, and utilities.

• Keep raw Umami calls in tracking.ts; preserve identify, queue, drain, SPA pageview deduplication, and tracked-referrer ordering.

• Keep analytics fail-open and accept only approved flat scalar fields; truncation or hashing does not make sensitive data safe.

• Preserve shared URL, interaction, lesson-feedback, audio, and storage semantics when changing helpers.

Avoid

• Do not move request or auth-header behavior into pages or components when lib/request.ts already owns that path.

• Do not reimplement shared normalization helpers in feature code when they belong here.

• Do not change shared utility contracts without rerunning affected tests and type checks across consumers.

• Avoid pushing domain-local rules up to shared docs unless another frontend subtree truly depends on the same constraint.

Commands

• rg -n "lib" src/web/src to locate call sites before editing this subtree.

• cd src/web && npm run type-check after TypeScript, store, hook, request, or route-contract changes.

• cd src/web && npm run lint before closing the task when shared frontend code or route files changed.

• cd src/web && npm run test -- src/lib/ for focused Jest coverage when this subtree already has or gains tests.

Tests

• Add or update focused tests closest to src/web/src/lib/ for the happy path and the most important regression or business-code error path.

• Rerun type-checking and linting when exported props, store fields, hook contracts, or route behavior move.

• When a domain depends on shared request or normalization helpers, update those tests or add new ones in the same task.

• Document skipped UI, browser, or provider-dependent verification in the task summary when local automation cannot cover it.

Related Skills

• src/web/skills/module-augmentation-guardrails/SKILL.md

• src/web/skills/deep-link-lessonid-routing/SKILL.md

• src/web/skills/interaction-user-input-defaults/SKILL.md

• src/web/skills/listen-mode-audio-streaming/SKILL.md

• src/web/SKILL.md

• SKILL.md

• Create a focused skill under src/web/skills/<topic>/SKILL.md when the same debugging or migration workflow repeats.