iptvnator/AGENTS.md

Repository guidance

IPTVnator is an Angular/Electron IPTV player with a browser/PWA runtime. These are the common instructions for all coding agents. Read the relevant contracts below before changing a subsystem; do not load every document.

Bootstrap and commands

• Use the Node version in .nvmrc and the repository's pnpm version.
• In a fresh worktree, run pnpm install --frozen-lockfile before Nx discovery, tests, lint or builds. Each worktree needs its own install.
• Repeat the install after checkout changes, pulls, resets or rebases. Compare pnpm-lock.yaml with node_modules/.pnpm/lock.yaml; a difference means stale dependencies. Do not diagnose stale modules as application failures.
• Verify discovery with pnpm nx show projects. Inspect the owning project's targets before choosing checks. Prefer the smallest relevant Nx target.
• Development: pnpm run serve:frontend or pnpm run serve:backend.
• Tests: pnpm nx test <project>; lint: pnpm nx lint <project>.
• Find checks and E2E commands in the validation map.
• Packaging, native dependencies and runtime patches have additional contracts in the context map; read them before dependency or release changes.

Implementation invariants

• Use scoped aliases from tsconfig.base.json, such as @iptvnator/services. Do not introduce legacy bare aliases or bypass public project boundaries.
• Nx projects keep scope:*, domain:* and type:* tags. Shared cross-project files must belong to a project. SCSS imports need explicit hash dependencies.
• Target under 300 production TypeScript lines; the hard limit is 400 (1200 for tests), excluding comments/blanks. Never add entries to the legacy baseline.
• Preserve existing persisted data. Users may skip releases: migrations must apply in dependency order, preserve data and be safe on repeated startup. Test actual historical SQLite schemas, not only SQL mocks.
• Choose runtime behavior through the relevant capability contract; a generic window.electron check does not prove that a particular bridge is available.
• Use shared redacting logging before emitting settings, portal or trace data. Never log credentials or expanded SQL/bound values.
• Keep UI consistent with the shared guidelines. Read the repository UI/theme skills before changing user-visible Angular views or shared styles.

Validation and completion

• Before finishing, assess affected projects and test impact. Bug fixes normally include regression coverage that fails before the fix and passes afterwards.
• Update stale tests, fixtures and E2E flows when behavior changes. Run targeted unit checks and affected E2E for routing, persistence, playback and user flows.
• Electron-only IPC, database, packaging, players and filesystem changes need Electron E2E where available, otherwise CDP/manual validation with a reason.
• Report checks and results, any skipped checks with reasons, documentation changes, and whether a release note was added or why it was unnecessary.
• Every user-visible change needs a note under .changes/; follow the release-note format and the repository release-notes skill. Docs, tests, CI and behavior-preserving refactors do not need a note. Apply no-release-note on exempt PRs touching runtime code.
• Validate notes with pnpm run release:notes:validate. Release publication has separate ordered gates; follow the release-cut skill and release contract.

Keep guidance small and canonical

• Update the affected subsystem's canonical document after meaningful changes. Prefer an existing authoritative doc; keep user/developer entry points in README and detailed contracts in architecture docs or a module README.
• Add to this file only repository-wide rules and navigation. Implementation details, incident history and multi-step procedures belong in linked docs. Do not duplicate subsystem contracts here or in CLAUDE.md.
• AGENTS.md is the single source of common rules. CLAUDE.md imports it and contains only Claude-specific guidance. Limits: 200 lines / 16 KiB here, 30 lines / 2 KiB for CLAUDE.md. Do not raise loading limits to fit more prose.
• Read the context map when ownership is unclear. Read each affected domain for cross-domain tasks, not the whole map's documents.
• Preserve exceptions and rationale when moving knowledge. Correct stale facts against code; do not silently discard a contract. Maintenance details are in the agent workflow.
• Never run whole-file prettier --write on AGENTS.md, CLAUDE.md or docs/**. Edit only intended lines; upstream Markdown is not uniformly Prettier-clean.
• After changing guidance, run pnpm run agents:validate; after editing a repository skill or a literal path it documents, run pnpm run skills:validate. Keep release-cut and release-notes copies byte-identical for Codex and Claude.
• Save finalized plans only in .plans/YYYY-MM-DD-short-topic.md; if a filename exists, append -2, -3, etc. Respect active mode restrictions on file writes; if writing is forbidden, save the approved plan when execution starts.

Read by task

Task	Required starting point
Project layout, imports, dependencies, lint configuration	Nx boundaries
Angular conventions, docs and skills maintenance	Agent workflow
Electron debugging, CDP, trace flags	Electron debugging
SQLite, worker IPC, persistence migrations	DB worker, database migrations
M3U, XMLTV, startup, source health, OS playlist opening	M3U contracts, adding sources across layers
Xtream / Stalker	Xtream compatibility, Stalker contracts (affected provider only)
Player controls, diagnostics, radio, keep-awake	Controls contract
Embedded MPV, native runtime and packaging	Embedded MPV
UI, keyboard, detail navigation, remote control	UI guidelines, then matching topic in context map
PWA, backend networking, connectivity guard	PWA contract, host connectivity
Downloads, TMDB, multi-source, workspace, backup, website	Context map
Release or packaging metadata	Release pipeline, release-cut skill

Repository skills live in .codex/skills/. Their frontmatter owns trigger conditions; use the context map to locate a relevant skill. Read its linked contract before editing. A missing optional global skill/tool is not a blocker: use repository documentation and available CLI discovery.

General Guidelines for working with Nx

• For workspace exploration, use the nx-workspace skill when available; otherwise inspect project-local project.json files, pnpm nx show projects and pnpm nx graph.
• Run project tasks through local pnpm nx, not a global Nx installation.
• Use the Nx MCP server when available; otherwise use CLI discovery.
• Check node_modules/@nx/<plugin>/PLUGIN.md for plugin guidance when present.
• Never guess unfamiliar flags: consult --help or available nx_docs.

Scaffolding and generators

• Use the nx-generate skill first when available. Otherwise discover the generator with local Nx help and follow repository boundary rules.

When to use nx_docs

• Use available nx_docs for migrations, unfamiliar configuration and flags.
• Basic task syntax does not require a docs lookup; generator discovery belongs to the generator skill or local CLI help.