docs: add Alembic stamping reminder to AGENTS.md

Prevent future regressions where new migrations aren't added to the
entrypoint.sh stamping logic, causing crash-loops on pre-Alembic DBs.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: GeiserX

AGENTS.md

@@ -1,184 +1,65 @@
-# Telegram-Archive - AI Assistant Configuration
+# telegram-archive - AI Assistant Configuration
 
 ## Before Starting Any Coding Task
 
-1. Always create a new git worktree for the task
-2. Use the naming convention: `git worktree add -b ai/[task-description] ../Telegram-Archive-ai-[task-description]`
+1. Check existing worktrees with `git worktree list` and create a new one for this task if needed
+2. Use the naming convention: `git worktree add -b ai/<task> .worktrees/<task>`
 3. Navigate to the worktree directory before making any changes
 4. Commit changes when the task is finished. Merge to main, and clean the worktree.
 
-<!--
-This file is synced with LynxPrompt (Blueprint: bp_cmk483at3000001pdq0ohz0t5)
-
-Sync Commands:
-
-# Using LynxPrompt CLI (recommended):
-lynxp push    # Upload local changes to cloud
-lynxp pull    # Download cloud changes to local
-lynxp diff    # Compare local vs cloud versions
-
-# Install CLI: npm install -g lynxprompt
-# Login: lynxp login
-
-Docs: https://lynxprompt.com/docs/api
--->
-
-> **Project Context:** This is an open-source project. Consider community guidelines and contribution standards.
-
 ## Persona
 
-You assist developers working on Telegram-Archive.
-
-Project description: Own your Telegram history. Automated, incremental backups with a local web viewer that feels just like the real app. Docker-ready and supports public chat sharing
+You assist developers working on telegram-archive.
 
 ## Tech Stack
 
-- Python 3.11
-- Telethon (Telegram MTProto client)
-- FastAPI + uvicorn (web viewer)
-- SQLAlchemy async (ORM)
-- aiosqlite / asyncpg (database drivers)
-- APScheduler (cron scheduling)
-- Alembic (database migrations)
-- Jinja2 (HTML templates)
-- PostgreSQL / SQLite
+- Python
+- FastAPI
+- sqlalchemy
 
 > **AI Assistance:** Let AI analyze the codebase and suggest additional technologies and approaches as needed.
 
 ## Repository & Infrastructure
 
-- **Host:** github
-- **License:** gpl-3.0
-- **Architecture:** Dual-image Docker (shared codebase, separate entrypoints for backup and viewer)
+- **License:** mit
+- **CI/CD:** 
 - **Commits:** Follow [Conventional Commits](https://conventionalcommits.org) format
 - **Versioning:** Follow [Semantic Versioning](https://semver.org) (semver)
-- **CI/CD:** GitHub Actions
-- **Deployment:** Docker
-- **Docker Images:**
-  - `drumsergio/telegram-archive` — Backup scheduler (requires Telegram credentials)
-  - `drumsergio/telegram-archive-viewer` — Web viewer only (no Telegram client)
-- **Example Repo:** https://github.com/GeiserX/LynxPrompt (use as reference for style/structure)
-
-## Deployment Environments
-
-| Environment | Image Tag | Purpose |
-|-------------|-----------|---------|
-| **Production** | `vX.Y.Z` (semver) | Stable releases only |
-| **Development** | `:dev` | PR builds, pre-release testing |
-
-- **PRs build `:dev` tag** via `docker-publish-dev.yml` workflow
-- **Tags build semver** via `docker-publish.yml` workflow
-- Always test on dev environment before releasing to prod
-- See gitea docker compose for environment assignments
-
-## Release Guidelines
-
-### Creating Releases
-
-**Always use the release script** to ensure changelog is updated:
-
-```bash
-./scripts/release.sh v4.1.5
-```
-
-The script:
-1. Validates version format (vX.Y.Z)
-2. **Checks that CHANGELOG.md has an entry** for this version (fails if missing!)
-3. Creates and pushes the git tag
-4. GitHub Actions creates the release with changelog notes
-
-### Manual Process (if needed)
-
-1. **Update `docs/CHANGELOG.md`** FIRST:
-   - Add new section: `## [X.Y.Z] - YYYY-MM-DD`
-   - Document all changes: Added, Fixed, Changed, Removed
-   - Mark breaking changes with `### ⚠️ Breaking Change`
-   - Include migration steps if needed
-
-2. Commit the changelog update
-
-3. Tag: `git tag vX.Y.Z -m "Release vX.Y.Z"`
-
-4. Push: `git push origin vX.Y.Z`
-
-### Breaking Changes
-
-When introducing breaking changes:
-- Bump **MAJOR** version (e.g., v4.0.0 → v5.0.0)
-- Document in CHANGELOG with migration steps
-- Update README upgrade section if significant
-- Consider providing migration scripts in `scripts/`
-
-### Chat ID Format (CRITICAL)
-
-All chat IDs must use Telegram's **marked format**:
-- Users: positive (e.g., `123456789`)
-- Basic groups: negative (e.g., `-123456789`)
-- Supergroups/Channels: -100 prefix (e.g., `-1002240913478`)
-
-When documenting or configuring chat IDs, always use marked format!
+- **CI/CD:** 
 
 ## AI Behavior Rules
 
-- **Always enter Plan Mode** before making any changes - think through the approach first
+- Optimize code for LLM reasoning: prefer flat/explicit patterns, minimal abstractions, structured logging, and linear control flow
+- When you learn new project patterns or conventions, suggest updates to this configuration file
+- Always verify your work before returning: run tests, check builds, confirm changes work as expected
+- Reuse existing terminals when possible. Close terminals you no longer need
+- Always check documentation (via MCP or project docs) before assuming knowledge about APIs or libraries
+- **Use Plan Mode** for complex tasks, multi-step changes, or risky modifications
+- When stuck, **attempt creative workarounds** before asking for help
 
 ## Git Workflow
 
-- **Workflow:** Direct commits to master are acceptable for small fixes and documentation
-- For larger features or breaking changes, create a feature branch and open a PR
-- Create descriptive branch names when needed (e.g., `feat/add-login`, `fix/button-styling`)
-
-### Git Commit Identity
-
-**IMPORTANT:** Always use the correct GitHub identity for commits:
-
-```bash
-git config user.name "GeiserX"
-git config user.email "9169332+GeiserX@users.noreply.github.com"
-```
-
-- **GitHub User ID:** 9169332
-- **Username:** GeiserX
-- **No-reply email:** `9169332+GeiserX@users.noreply.github.com`
-
-⚠️ Using the wrong ID in the email (e.g., `57840286+...`) will link commits to a different GitHub account!
-
-## Important Files to Read
-
-Always read these files first to understand the project context:
-
-- `README.md` — Features, configuration, deployment
-- `src/config.py` — All environment variables and their handling
-- `src/telegram_backup.py` — Core backup logic
-- `.env.example` — Configuration reference
-- `docker-compose.yml` — Deployment patterns
-
-## Self-Improving Blueprint
-
-> **Auto-update enabled:** As you work on this project, track patterns and update this configuration file to better reflect the project's conventions and preferences.
+- **Workflow:** Create feature branches and submit pull requests
+- Create a descriptive branch name (e.g., `feat/add-login`, `fix/button-styling`)
+- Open a PR for review before merging
+- Do NOT commit directly to main/master branch
 
 ## Boundaries
 
 ### ✅ Always (do without asking)
 
-- Create new files
-- Rename/move files
-- Rewrite large sections
-- Change dependencies
-- Touch CI pipelines
-- Modify Docker config
-- Change environment vars
-- Update docs automatically
-- Edit README
-- Handle secrets/credentials
-- Modify auth logic
+- Read any file in the project
+- Modify files in src/ or lib/
+- Run build, test, and lint commands
+- Create test files
+- Fix linting errors automatically
 
 ### ⚠️ Ask First
 
-- Delete files
-- Modify database schema
-- Update API contracts
-- Skip tests temporarily
+- Add new dependencies to package.json
+- Modify configuration files at root level
+- Create new modules or directories
+- Refactor code structure significantly
 
 ### 🚫 Never
 
@@ -190,7 +71,7 @@ Always read these files first to understand the project context:
 ## Code Style
 
 - **Naming:** follow idiomatic conventions for the primary language
-- **Logging:** Python logging with `logger = logging.getLogger(__name__)`
+- **Logging:** [90m⏭ Skip[39m
 
 Follow these conventions:
 
@@ -201,114 +82,19 @@ Follow these conventions:
 - Add comments for complex logic only
 - Keep functions focused and testable
 
-## ⚠️ Data Consistency Rules (CRITICAL)
-
-These rules exist because of bugs that reached production. **Always verify these when modifying DB code.**
-
-### Chat ID Format (Marked IDs)
-
-Telegram uses "marked" IDs that differ from raw entity IDs:
-
-| Entity Type | Format | Example |
-|-------------|--------|---------|
-| Users | Positive | `123456789` |
-| Basic groups | Negative | `-123456789` |
-| Supergroups/Channels | -1000000000000 - id | `-1001234567890` |
-
-**Rules:**
-- Always use `telethon.utils.get_peer_id(entity)` to get the marked ID
-- Never use `entity.id` directly for database operations
-- The `_get_marked_id()` method in `telegram_backup.py` wraps this
-- User config (`GROUPS_INCLUDE_CHAT_IDS`, etc.) uses marked format
-
-### DateTime Timezone Handling
-
-Telethon returns timezone-aware datetimes, but PostgreSQL uses `TIMESTAMP WITHOUT TIME ZONE`.
-
-**Rules:**
-- Always strip timezone before DB insert/update using `_strip_tz(dt)` in `adapter.py`
-- Apply to ALL datetime fields: `date`, `edit_date`, `created_at`, etc.
-- Check both INSERT and UPDATE operations (v4.0.6 bug: insert used `_strip_tz`, update didn't)
-
-### Consistency Checklist
-
-When modifying database code, verify:
-- [ ] All chat_id values use marked format (via `_get_marked_id()`)
-- [ ] All datetime values pass through `_strip_tz()` before DB operations
-- [ ] INSERT and UPDATE operations handle the same fields identically
-- [ ] Tests exist in `tests/test_db_adapter.py` for data type handling
-
-## Alembic Migrations (CRITICAL)
-
-### Architecture
-
-- Migrations live in `alembic/versions/` with format `YYYYMMDD_REV_slug.py`
-- Sequential integer revisions: `001`, `002`, ..., `006`, etc.
-- `alembic/env.py` runs migrations via async SQLAlchemy (`asyncpg` for PG, `aiosqlite` for SQLite)
-- `scripts/entrypoint.sh` calls `alembic upgrade head` on container start (backup container only, not viewer)
-- The entrypoint also handles **pre-Alembic stamping** for databases that existed before migrations were added
-
-### Writing a New Migration
-
-1. Create file: `alembic/versions/YYYYMMDD_NNN_slug.py`
-2. Set `revision = "NNN"` and `down_revision = "NNN-1"`
-3. Use `op.add_column()`, `op.create_table()`, `op.create_index()`, etc.
-4. Both SQLite and PostgreSQL must be supported -- check `conn.dialect.name` when behavior differs
-5. Update the pre-Alembic stamping logic in `entrypoint.sh` if the new migration adds detectable schema (table, index, column) so existing databases get stamped correctly
-
-### Advisory Lock Rule (v6.2.14 bugfix)
-
-**NEVER execute SQL on the Alembic connection before `context.configure()`.**
-
-Any `connection.execute()` before `configure()` triggers SQLAlchemy's autobegin. Alembic then detects `_in_external_transaction=True` and returns `nullcontext()` from `begin_transaction()`, skipping its own commit. DDL runs but is silently rolled back when the connection closes.
-
-The correct pattern in `env.py`:
-
-```python
-def do_run_migrations(connection):
-    context.configure(connection=connection, ...)  # FIRST — no SQL before this
-
-    with context.begin_transaction():
-        # Advisory lock INSIDE the transaction, using xact variant (auto-releases on commit)
-        if connection.dialect.name == "postgresql":
-            connection.execute(text("SELECT pg_advisory_xact_lock(7483920165)"))
-        context.run_migrations()
-```
-
-### Entrypoint Stamping
-
-`entrypoint.sh` detects pre-Alembic databases and stamps them at the correct version by checking for schema artifacts (tables, columns, indexes). When adding migration `NNN`, add a detection check for it in the stamping logic so fresh installs and upgrades from any version work correctly.
-
 ## Testing Strategy
 
 ### Test Levels
 
-- **Smoke:** Quick sanity checks for critical paths
 - **Unit:** Unit tests for individual functions and components
 - **Integration:** Integration tests for component interactions
-- **E2e:** End-to-end tests for full user flows
 
 ### Frameworks
 
 Use: pytest
 
 ### Coverage Target: 80%
 
-### CI Requirements
-
-**All PRs MUST pass tests before merge.** The `Tests` workflow runs on every PR:
-- `tests/test_db_adapter.py` — Data type consistency (timezone, chat IDs)
-- `tests/test_config.py` — Environment variable parsing
-- `tests/test_telegram_backup.py` — Core backup logic
-
-### When to Add Tests
-
-Add tests when:
-1. Fixing a bug — write a test that would have caught it
-2. Adding DB operations — test data type handling
-3. Modifying config parsing — test edge cases (empty strings, etc.)
-4. Adding new features — test the happy path and error cases
-
 ## 🔐 Security Configuration
 
 ### Secrets Management
@@ -320,10 +106,6 @@ Add tests when:
 - Dependabot (dependency updates)
 - Renovate (dependency updates)
 
-### Authentication
-
-- Basic Authentication
-
 ### Data Handling & Compliance
 
 - Encryption at Rest
@@ -337,6 +119,13 @@ Add tests when:
 
 **🔍 Security Audit Recommendation:** When making changes that involve authentication, data handling, API endpoints, or dependencies, proactively offer to perform a security review of the affected code.
 
+## Alembic Migrations — Critical Reminders
+
+- **`Base.metadata.create_all(checkfirst=True)`** creates ALL tables from SQLAlchemy models at once, including tables that should be created by future Alembic migrations. This means pre-Alembic databases can have schema objects from migrations that haven't "run" yet.
+- **`scripts/entrypoint.sh`** stamps pre-Alembic databases by detecting which schema objects exist. **Every time you add a new migration, you MUST update the stamping logic in entrypoint.sh** — both the PostgreSQL block and the SQLite block — to detect the new migration's artifacts (tables, columns, indexes). If you forget, existing databases that were created via `create_all()` will be stamped at a lower version, and Alembic will try to re-create objects that already exist, causing crash-loops.
+- Check highest migration first, then descend (009 → 008 → 007 → ...).
+- Test with both PostgreSQL and SQLite paths.
+
 ---
 
-*Generated by [LynxPrompt](https://lynxprompt.com) CLI*
+*Generated by [LynxPrompt](https://lynxprompt.com) CLI*Always use Python type hints for public APIs.