Organize documentation into topic folders (Claude, Python, Zscaler, Project template)

Claude/AGENTS.md

@@ -0,0 +1,83 @@
+# AI Agents - Project Rules
+
+**Document Version:** v4 (independent, incremented on structural changes)
+
+Rules and instructions for AI assistants (Claude Code, Cursor, Copilot, etc.)
+
+## First-time setup
+
+- **On first read of this file, immediately read all other `.md` files in the project root** (e.g. `PROJECT.md`, `CHANGELOG.md`, `DESIGN_DOCUMENT.md`) to get full project context before starting any task.
+
+## Language
+
+- **Always write all documentation in English**
+
+## Dependency Management
+
+- **Always use `poetry add`** to add dependencies, **never edit `pyproject.toml` directly**
+  ```bash
+  poetry add requests
+  poetry add --group dev pytest
+  ```
+- Use `poetry remove` to remove dependencies — **never edit `pyproject.toml` manually**
+
+## Project Structure
+
+- Entry points are in the project root (named after project or by purpose: `project_name.py`, `cli.py`, `gui.py`, `server.py`)
+- A project can have multiple entry points
+- All modules belong in the `src/` folder
+- Tests belong in the `tests/` folder
+- Virtual environment is in `.venv/` (do not copy, do not generate)
+
+## Code
+
+- Always use type annotations
+- Follow PEP8 and format with Ruff (88 characters per line)
+- Before commit run `poetry run ruff check` and `poetry run mypy`
+
+## Testing
+
+- **Use pytest exclusively** - never use the `unittest` module
+- No `unittest.TestCase` classes, no `self.assert*` methods
+- Use plain `assert` statements and pytest fixtures
+
+## Running
+
+- Use `poetry run` to run scripts:
+  ```bash
+  poetry run python project_name.py
+  poetry run pytest
+  ```
+
+## Logging
+
+- Use **loguru** for logging - never use `print()` for debugging
+- Never log secrets, passwords, tokens, or API keys
+
+## Environment and Secrets
+
+- Store secrets in `.env` file with `ENV_DEBUG=true/false` variable
+- Load secrets using `python-dotenv` and `os.getenv()`
+- **Never commit `.env` file**
+
+## Git
+
+- `.gitignore` should contain: `.venv/`, `__pycache__/`, `*.pyc`, `.mypy_cache/`, `.env`
+- Do not commit `poetry.lock` only if it's a library (for applications, commit it)
+- **Never commit this documentation** (`DESIGN_DOCUMENT.md`, `AGENTS.md`, `.claudeignore`)
+- `PROJECT.md` **should be committed** - it's project-specific
+
+## Versioning
+
+- **Always ask user before bumping version** - never increase version automatically
+- **Keep `CHANGELOG.md` updated** - document all significant changes as they are made
+- Update `CHANGELOG.md` with changes before version bump
+- Version is defined in `pyproject.toml` under `[project]` section
+- Follow semantic versioning (MAJOR.MINOR.PATCH)
+
+## Task Management
+
+- **When completing tasks, mark them as done** - if you finish any task with a checkbox anywhere in project documentation, check it off as completed `[ ]` → `[x]`
+- **Track all work** - this applies to tasks in `PROJECT.md` (TODO section, Development Roadmap, any checklists) and other documentation
+- **Update documentation** - when completing changes, update relevant sections in `PROJECT.md`, `CHANGELOG.md`, and architecture diagrams
+- **Keep task lists current** - completed items with `[x]` stay visible to show progress history

Claude/CLAUDE.md

@@ -0,0 +1,10 @@
+
+## First-time setup
+
+**At the start of every new session, read all of the following files before doing anything else:**
+
+- `CLAUDE.md` (this file)
+- `AGENTS.md`
+- `PROJECT.md`
+- `CHANGELOG.md`
+- `DESIGN_DOCUMENT.md`

Claude/skills/changelog/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: changelog
+description: Updates changelog in project
+---
+
+Take known info and make changes to CHANGELOG.md to make them up-to-date.
+
+Ignore changes to: `docs/`, `CONTEXT.md`, `Documentation_AI.md`, `Documentation_human.md` — documentation and context files are not logged in the changelog.

Claude/skills/check/SKILL.md

@@ -0,0 +1,5 @@
+---
+name: check
+description: Check for failed tests
+---
+Try running tests and investigate failed results

Claude/skills/commit/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: commit
+description: Updates changelog and proposes a concise verbal git commit message
+---
+
+1. Run the changelog skill: read git log and staged changes, then update CHANGELOG.md accordingly (same as /changelog).
+
+2. Propose a single-line verbal commit message:
+   - Concise, verbal style — e.g. "Add X", "Fix Y", "Refactor Z"
+   - NOT filename-style — never "update_something.py" or "changes to foo"
+   - In English
+   - Do NOT run git commit — only propose the message and wait for user confirmation.

Claude/skills/context/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: context
+description: Compress docs/ into CONTEXT.md at project root — minimum tokens, lossless
+---
+
+Read every `.md` file in `docs/`. Generate `CONTEXT.md` at the project root.
+
+## Goal
+
+Lossless compression of `docs/` into a single file optimised for LLM context window use.
+Every public function, class, constant, invariant, file path, and edge case from `docs/` must be present.
+Target: CONTEXT.md ≈ 40–50% byte size of combined `docs/` input.
+
+## Format rules
+
+- Symbol legend at top: `Legend: → returns  * required  ? optional  @ located at`
+- Tables over paragraphs — always
+- Compact signature notation: `f(a:T, b:T) → T @ src/foo.py`
+- Pipe unions: `A | B | C`
+- Section references: §0, §1, … — state each fact once, reference elsewhere
+- Inline conditions: `if X: Y; else: Z`
+- No prose, no motivation, no examples that just illustrate a stated rule
+- No headings deeper than 3 levels
+
+## Sections
+
+- §0 Module map — path + 1-line role
+- §1 Data types — every class: fields, types, invariants
+- §2 Public API — every public function/method: compact signature + constraints
+- §3 Constants — table: name, value, file, where used
+- §4 Workflows — compact arrow notation
+- §5 Configuration — env vars, defaults
+- §6 Edge cases & invariants — one row per rule, exhaustive
+- §7 Build / run / test — exact commands
+
+## When to skip
+
+If `CONTEXT.md` exists and no file in `docs/` is newer than it: print `context: in sync` and stop.

Claude/skills/documentation/SKILL.md

@@ -0,0 +1,5 @@
+---
+name: documentation
+description: Updates documentation in project
+---
+Create or update documentation of project in docs/ folder. Documentation should contain description of each part of program and documentation of each function. Separate documents for each module. Write in markdown format.