diff --git a/AGENTS.md b/AGENTS.md deleted file mode 100644 index 8984434..0000000 --- a/AGENTS.md +++ /dev/null @@ -1,97 +0,0 @@ - -# 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](https://www.conventionalcommits.org/) 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**: - ```bash - 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: - ```bash - .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](https://github.com/zhanymkanov/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:** -```text -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 \ No newline at end of file diff --git a/CLAUDE.md b/CLAUDE.md index d43830a..c6055da 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,17 +1,101 @@ -# Claude Code Instructions +# CLAUDE.md โ€” Library Desk -**MANDATORY: Read AGENTS.md instead of this file.** +FastAPI service that ingests Wiki.js content and serves retrieval over it. Talks to +Postgres (Wiki.js DB + `LISTEN/NOTIFY`), Qdrant (vectors), Neo4j (graph), Ollama +(embeddings) and Redis (job manager). Deployed on tower-of-joy at **:8089**. -This project uses a unified configuration file for all LLM coding agents. +## Ports โ€” these differ, deliberately -## Instructions +| | Port | How | +|---|---|---| +| Local dev | **8778** | `./wakeup.sh`, uvicorn reload mode, logs to `logs/server.log` | +| Production | **8089** | container; health at `http://192.168.86.149:8089/health` | -1. **Read and follow AGENTS.md** - All project guidelines are located there -2. **Do not modify this file** - Only update AGENTS.md -3. **Do not create or modify other agent-specific files** - Use AGENTS.md as the single source of truth +Testing `localhost:8089` on the dev box hits the *container*, not your reload server. -This approach ensures consistent behavior across all LLM coding agents without managing separate configuration files. +## Work tracking ---- +Work lives in **pql**, not a markdown file. `TODO.md` was migrated and removed 2026-08-08. -If you need to update project guidelines, edit AGENTS.md, not this file. +```bash +pql ticket list # open work +pql plan whatsnext # next unblocked item, with context +pql ticket show T-1 # detail +pql ticket new bug "title" # file new work +``` + +Tickets travel with the repo โ€” `.pql/changelog/` is committed and replayed by the git +hooks; the databases are ignored and rebuildable with `pql plan rebuild`. Do not add a +TODO section to a markdown file. + +## Known live defect + +**Every wiki page change is ingested twice** (T-1, proven against v1.9.1). The Dockerfile +runs `uvicorn --workers 2`, `startup_event` creates a `WikiChangeListener` per worker, and +Postgres delivers `NOTIFY` to *every* listening session. The debounce in +`wiki_change_listener.py` is an in-process dict and cannot dedupe across workers. + +Relevant when touching ingestion: duplicate work reaches Ollama, Qdrant and Neo4j. Whether +it merely wastes GPU or actually corrupts state is **not yet established** โ€” check before +assuming either. + +## Working here + +**Plan, act, reflect.** Outline which files you will touch and the side effects before +writing. Change in small atomic steps. Afterwards, verify: did existing tests break, and +does the new behaviour have a test? + +**Test locally first โ€” the build-deploy loop is slow.** `./wakeup.sh` auto-reloads on code +changes (not on `requirements.txt` changes). Deploy only when a feature is complete and +tested. + +Run tests through the venv explicitly, to avoid environment mismatch: + +```bash +.venv/bin/python -m pytest tests/ +``` + +Copy `.env.example` to `.env` and configure Ollama, Redis, Neo4j, Qdrant and Wiki.js hosts. + +## Git + +- **History is linear โ€” no merge commits.** Work on `main`, or a short-lived branch that is + fast-forwarded and deleted. (A feature-branch mandate was retired 2026-08-08 to match the + workspace convention, which now has no per-repo exceptions.) +- **Conventional Commits**: `feat:`, `fix:`, `refactor:`, `docs:`, `chore:`. +- **Atomic commits** โ€” one logical change each. +- **Stage explicitly. Never `git add -A`** โ€” it is denied by policy, and it sweeps in + whatever else is dirty, including secrets. +- Update `CHANGELOG.md` with every user-facing change, under `[Unreleased]` in `Added` / + `Changed` / `Fixed`. + +## Releasing + +Ask whether a deploy is wanted first โ€” it is not automatic. + +1. Bump the version in `pyproject.toml` (patch for fixes, minor for features). +2. Move `[Unreleased]` entries into a dated version section in `CHANGELOG.md`. +3. Stage the changed files by name, commit, tag `vX.Y.Z`, `git push origin main --tags`. +4. Gitea CI builds the image on the tag; Watchtower deploys it. +5. Verify: `curl http://192.168.86.149:8089/health`. + +## Architecture + +Group by **domain, not by file type**. A single large `routers/` folder is the thing to +avoid. + +```text +src/ +โ”œโ”€โ”€ auth/ +โ”‚ โ”œโ”€โ”€ router.py # endpoints +โ”‚ โ”œโ”€โ”€ schemas.py # pydantic models +โ”‚ โ”œโ”€โ”€ service.py # business logic +โ”‚ โ”œโ”€โ”€ dependencies.py # module-scoped dependencies +โ”‚ โ””โ”€โ”€ config.py # module-scoped settings +โ””โ”€โ”€ main.py # app entry point +``` + +Reference: [FastAPI best practices](https://github.com/zhanymkanov/fastapi-best-practices). + +The live contract is always `http://localhost:8089/openapi.json` (70 paths) โ€” generated from +running code, so it cannot drift the way this file can.