Project operating rules

Development server

Always bind the Django development server to 0.0.0.0:8000 so the project is reachable from phones and other devices through the computer's local-network IP address. Do not start it on 127.0.0.1 unless the user explicitly requests localhost-only access.
Before starting or restarting Django on port 8000, inspect the port and identify every existing listener.
Stop the previous project server and its parent/child process tree before launching the replacement.
After launch, verify that exactly one process is listening on port 8000.
Verify the listener is bound to 0.0.0.0:8000, then fetch the site locally through 127.0.0.1:8000 as a health check.
Fetch a changed page/static asset from the live server and confirm the expected new content is actually being served.
When frontend assets change, remind the user to perform a hard refresh, but do not treat browser cache as the cause until the live listener and served content have been verified.
Keep the active server session identifier and shut it down cleanly before starting another instance.

Treat questions about this codebase as Graphify queries first whenever graphify-out/graph.json exists.
Before querying, expand the user's Persian question against the actual vocabulary in graphify-out/graph.json.
Use the best combination of Persian and English terms that are present in the graph vocabulary; never rely on automatic translation, stemming, or synonyms inside Graphify.
For code queries, prioritize the graph's English identifiers (class, function, model, template, route, and file names), because the structural code graph is predominantly English; add Persian terms when they actually exist in the graph, especially for requirements and documentation.
Choose the traversal deliberately: BFS for broad relationships, DFS for dependency/data-flow traces, path for a shortest connection, and explain for one node and its neighbors.
Validate important Graphify findings against the referenced source code or project documentation before acting on them.

Use Liara's PyPI mirror for Python dependency resolution and installation: https://package-mirror.liara.ir/repository/pypi/simple.
Prefer the persistent user-level pip configuration over repeating --index-url in individual commands.
If the mirror is temporarily unavailable or missing a required package/version, report it before using the public PyPI index as a fallback.

Every locally served frontend asset in templates must include static_asset_version in its URL.
Keep the service-worker registration URL versioned with the same value and keep updateViaCache: 'none'; changing only the service-worker cache name is not sufficient.
Any change to frontend caching or PWA lifecycle code must preserve the regression assertions in tests/test_views.py and pass tests/e2e/test_pwa_versioning.py with service workers enabled.
Before blaming a user's browser cache, verify the live listener and served asset content according to the development-server rules above.

Put browser scenarios under tests/e2e/, mark them e2e, and use Django's transactional live_server.
Use the managed Chromium and isolated BrowserContext provided by tests/e2e/conftest.py; do not launch browsers directly inside tests. Keep Playwright function-scoped because a session-scoped sync Playwright event loop conflicts with Django's synchronous test-database setup.
Keep selectors and reusable browser actions in tests/e2e/pages/ Page Objects, while tests remain focused on user-visible outcomes.
Never use fixed sleeps for synchronization. Use Playwright locators, expect, navigation, response, or application-state waits.
Preserve automatic screenshot and trace capture on failure. PWA scenarios must explicitly enable service workers and carry the pwa marker.