library-desk/AGENTS.md

AGENTS.md

Start every session by reading this file. This file outlines the operational protocols, coding standards, and architectural decisions for this FastAPI project.

1. Agent Operational Protocols

🧠 Work Patterns (Plan-Act-Reflect)

• Plan: Before writing code, briefly outline your plan. Identify which files you will touch and what the side effects might be.
• Act: Execute the changes in small, atomic steps.
• Reflect: After coding, verify your work. Did you break existing tests? Did you add new tests?

📋 Work Tracking

• Outstanding work lives in pql, not in a markdown file. TODO.md was migrated on 2026-08-08 and removed.
• pql ticket list — open work. pql plan whatsnext — the next unblocked item with context. pql ticket show T-N --with-children — detail.
• File new work with pql ticket new bug|task|story|epic "title" rather than adding a TODO section. Tickets travel with the repo: .pql/changelog/ is committed and replayed by the git hooks, while the databases are ignored and rebuildable (pql plan rebuild).

🛡️ Git Discipline

• History is linear — no merge commits. Work goes onto main directly, or onto a short-lived branch that is fast-forwarded and deleted. Never create a merge commit. (This replaced a feature-branch mandate on 2026-08-08, to match the workspace convention; tatlock remains the one repo that requires branches.)
• Commit Messages: Use the Conventional Commits format.
  • feat: add user login endpoint
  • fix: resolve database connection timeout
  • refactor: split monolith dependency file
• Atomic Commits: Keep commits small. One logical change = one commit.

📝 Changelog Maintenance

• Update CHANGELOG.md with every user-facing change.
• Format: ## [Unreleased] - YYYY-MM-DD followed by ### Added, ### Changed, or ### Fixed.

🚀 Release Flow

When changes are ready for deployment:

1. **Ask user if deploy cycle is desired **

2. Update version in pyproject.toml:

   • Bug fixes: bump patch version (1.8.3 → 1.8.4)
   • New features: bump minor version (1.8.4 → 1.9.0)

3. Update CHANGELOG.md:

   • Move items from [Unreleased] to new version section
   • Add release date: ## [1.8.4] - 2025-12-16

4. Commit and tag:

   git add -A
   git commit -m "fix: description of changes"
   git tag v1.8.4
   git push origin main --tags
   

5. CI/CD triggers automatically:

   • Gitea CI builds Docker image on new tag
   • Watchtower pulls and deploys to production
   • Verify deployment: curl http://192.168.86.149:8089/health

---

🧪 Local Development Setup

• Always test locally first before committing and deploying. The build-deploy loop is slow.
• Start the local server with ./wakeup.sh - logs are written to logs/server.log for easy tailing
• Auto-reload: The wakeup script runs uvicorn in reload mode - code changes are picked up automatically without restart (except for requirements.txt changes)
• Test REST endpoints against http://localhost:8778 using curl or similar tools
• Only deploy when a phase or feature is complete and tested locally
• Environment: Copy .env.example to .env and configure for your local setup (Ollama, Redis, Neo4j, Qdrant, Wiki.js hosts)
• Running tests: Always use the venv explicitly to avoid environment mismatches:

  .venv/bin/python -m pytest tests/           # All tests
  .venv/bin/python -m pytest tests/ -v        # Verbose output
  

---

2. FastAPI Architecture & Best Practices

Reference: FastAPI Best Practices

📂 Project Structure (Directory-based, NOT File-type based)

Do not group files by type (e.g., one huge routers folder). Group by domain/module inside a src/ directory.

Correct Structure:

src/
├── auth/
│   ├── router.py      # Endpoints
│   ├── schemas.py     # Pydantic models
│   ├── service.py     # Business logic (CRUD, etc.)
│   ├── dependencies.py# Module-specific dependencies
│   └── config.py      # Module-specific settings
├── posts/
│   ├── router.py
│   └── ...
└── main.py            # App entry point