free-claude-code CLAUDE.md

AGENTIC DIRECTIVE

Keep AGENTS.md and CLAUDE.md identical.

CODING ENVIRONMENT

• Install astral uv using "curl -LsSf https://astral.sh/uv/install.sh | sh" if not already installed and if already installed then update it to the latest version
• Install Python 3.14.0 stable using uv python install 3.14.0 if not already installed (requires uv >=0.9; see [tool.uv] required-version in pyproject.toml)
• Always use uv run to run files instead of the global python command.
• Current uv ruff formatter is set to py314 which has supports multiple exception types without paranthesis (except TypeError, ValueError:)
• Read .env.example for environment variables.
• All CI checks must pass; failing checks block merge.
• Add tests for new changes (including edge cases).
• Before pushing, prefer ./scripts/ci.sh (macOS/Linux) or .\scripts\ci.ps1 (Windows) to run the local CI sequence; requires uv on PATH. The local scripts run Ruff in repair mode (ruff format, then ruff check --fix) before type checking and tests.
• Use --only / --skip (PowerShell: -Only / -Skip) to run a subset when iterating; use --dry-run to print commands without running them.
• GitHub CI remains check-only for Ruff (ruff format --check, ruff check) so branch protection verifies committed code.
• Fall back to individual repair commands when debugging local failures: uv run ruff format, uv run ruff check --fix, uv run ty check, uv run pytest -v --tb=short. Use GitHub-style checks only when verifying enforcement locally: uv run ruff format --check, uv run ruff check.
• Do not add # type: ignore or # ty: ignore; fix the underlying type issue.
• Do not add from __future__ import annotations; Python 3.14 native lazy annotations are the project standard.
• All 6 check IDs are represented in scripts/ci.sh / scripts/ci.ps1 and enforced by tests.yml before each merge (parallel jobs: suppression grep, ruff-format, ruff-check, ty, pytest, playwright).
• Deterministic rendered Admin UI interactions live under e2e/ and run separately from ordinary pytest. Install Chromium once with uv run playwright install chromium; API and unit contracts remain under tests/.
• GitHub CI runs for every pull request, including stacked PRs targeting non-main branches. Head updates trigger fresh checks; strict required checks keep PRs targeting main current with main, so the tested PR tree is the tree squash-merged without a duplicate post-merge run.
• A separate trusted Dependency Cache workflow runs after pushes to main only and is the sole writer for reusable Python and uv dependency caches. Pull-request jobs only restore caches; the maintenance workflow never reruns validation and is not a required status check.
• Repository protection should use rulesets: a non-bypassable main integrity ruleset requires pull requests and strict required checks, keeps branches current, and blocks direct/force pushes to main; a separate review ruleset may allow Alishahryar1/admins to bypass review only.
• Required status checks: set required status checks to all of those statuses (e.g. Ban suppressions and legacy annotations, ruff-format, ruff-check, ty, pytest, playwright—use the exact labels GitHub shows, which may be prefixed with CI /). Remove ci from required checks if it was previously added for the old gate job.