# AI AGENT RULES - MANDATORY ENTRY POINT

**READ THIS ENTIRE FILE BEFORE EXECUTING ANY TASK.**
This is the **Single Source of Truth** for ALL Artificial Intelligence agents (Claude, Gemini, etc.) working on this project. 
(Automatic IDE entry points like `GEMINI.md` and `CLAUDE.md` exist solely to redirect agents to this main file).
For technical architecture, data models, and stack details, refer to [PROJECT_ARCHITECTURE.md](PROJECT_ARCHITECTURE.md).

## 1. Multi-AI Coordination & Memory
- **MANDATORY STARTUP**: Every AI session MUST first read `dev_docs/SESSION_STATE.md` to understand current context.
- **MANDATORY HANDOVER**: At the end of every task/session, update the handover note in `dev_docs/SESSION_STATE.md`. Specify: **Active AI**, **Current Status**, **Technical Context**, and **Next Steps**.
- **ARCHIVAL RULE**: Before writing new state, move all content of the *previous* session handover into the top of `dev_docs/SESSION_HISTORY.md` to prevent bloat.
- **NO INTERACTION OVERLAP**: Never modify a file if another AI session is explicitly working on it.

## 2. Global Operational Laws
- **STRICT ENGLISH POLICY**: All web interfaces, code, variables, scripts, and documentation MUST BE DIRECTLY AND ONLY IN ENGLISH. If you find Romanian text in code, translate it immediately.
- **COMMUNICATION LANGUAGE**: Conversation with the user will be in Romanian or English (preferably Romanian).
- **GIT BINARY PATH**: On this macOS environment, the system `git` is often broken. ALWAYS use the binary path stored in `.git_path` at the project root for all Git operations.
- **COMMIT & PUSH STRICT RULE**: 
  - Never push to remote (`git push`) or use force flags (`--hard`, `--force`) unless explicitly requested. 
  - Always update `VERSION.json` on every commit.
  - Do NOT add AI co-author signatures (e.g., `Co-Authored-By: AI...`) to commit messages.
  - Branching: `master` (stable), `dev` (active development), `vX` (archival releases).
- **PACKAGE MANAGEMENT**: Any new package installed via `pip install` MUST be added to `backend/requirements.txt` with version constraints (e.g., `slowapi>=0.1.9`). Keep requirements.txt synchronized with installed packages.
- **MANDATORY LOGGING**: Document coding/architecture changes in `dev_docs/ARCHIVE_LOGS.md` at the end of the task.
- **TRIPLE CONFIRMATION (Safe Forget)**: You cannot delete a physical location, item, or critical entity without explicit user permission three times.

## 3. UI/UX Fidelity Specifications
- **Fidelity First**: Never simplify the UI unless asked. Density and aesthetics must remain "Premium".
- **Styling**: Tailwind CSS. Font weights/spacing must be consistent (Inter/Roboto).
- **Readability**: NO `uppercase` or `tracking-widest` styles. Use standard camel/Title case.
- **Icons**: Use **Lucide Icons** exclusively. NO emojis.
- **Interactive Affordance**: All select/dropdown boxes MUST have a `ChevronDown` icon. Masked passwords should have reduced opacity (`text-white/50`).
- **Iconography Standardization**:
  - **Categories**: ALWAYS use `Layers` (Color: `text-primary`).
  - **Item Types**: ALWAYS use `Package` (Color: `text-green-500`).

## 4. Documentation Maintenance
- **SSOT INTEGRITY**: Whenever a feature is added, modified, or removed, you MUST update all corresponding documentation files:
  - `README.md` (General usage & technical modes).
  - `USER_GUIDE.md` (End-user instructions).
  - `PROJECT_ARCHITECTURE.md` (Technical logic & data models).
  - `export_prod.sh` (If new scripts or files must be included in the production bundle).
- **REAL-TIME UPDATES**: Documentation updates are NOT optional and must be performed within the same session as the code changes.

## 6. AI Command Shortcuts
- **`save-version`**: When the user triggers this command, the AI MUST:
  1. Increment the patch version in `VERSION.json`.
  2. Stage all current changes (`git add .`).
  3. Commit changes with message `Build [vX.Y.Z]`.
  4. Create a new branch named `vX.Y.Z` from the current state.
  5. Generate a production bundle ZIP (calls `./export_prod.sh`).
  6. Stay on the current branch (`dev`).
  - *Implementation*: Use `python3 scripts/save_version.py` to ensure consistency.

## 7. UI Fidelity Laws (Strict)
- **Consistent Layout**: All main pages (Inventory, Audit, Admin) MUST use `max-w-7xl` for their primary content container.
- **Unified Headers**: Every functional page MUST have an identical header structure:
  - Icon inside a styled box (`p-4 bg-primary/10 rounded-[2rem] border border-primary/20`).
  - Title: `text-3xl font-black text-white tracking-tight`.
  - Subtitle: `text-xs text-slate-500 font-bold mt-1 tracking-wider`.
- **Typographic Integrity**: 
  - **NO UPPERCASE** (ALL CAPS) allowed anywhere in the UI (headers, labels, buttons, metadata).
  - **NO ITALICS** in headers, titles, or active UI elements.
  - Consistent font weight (`font-black`) for main headings.
- **Safety Actions**:
  - The **Logout** button MUST be clearly differentiated (e.g., `text-rose-500`) and MUST always require a `window.confirm` before execution.

## 8. Audit & Deletion Policy
- **Immutability of Logs**: Deleting an `Item` MUST NOT delete its corresponding entries in the `AuditLog` table in the database.
- **Disk Traceability**: Every item deletion MUST be logged to the disk file (`logs/backend.log`) with `USER[id]`, `ITEM[id]`, `Name`, and `PN`.
- **Explicit Confirmation**: Destructive actions (Delete Item from catalog) MUST always trigger a browser-native `window.confirm` before proceeding.


## 5. End of Session Protocol
- Once a phase/task from `PLAN.md` is completed and verified, move that entry into `dev_docs/PLAN_HISTORY.md`.
- After finishing an entire job (including updating session state, architecture logs, and versioning), end your final response on a separate line exactly with:
  ```
  ---
  ✓ Done.
  ```
- Do not provide unnecessary verbatim summaries of the code.