# 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.

## Graphify queries

- 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.

## Python package mirror

- 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.

## Frontend and PWA cache safety

- 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.

## End-to-end browser tests

- 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.