ai-journal-mcp: Instructions file for Claude Code

Claude Rules

This file: how Claude behaves in this repository. Architecture, specifications, and decisions live in the docs linked below; this file points rather than restates.

Where Things Live

Hard Constraints

1. Markdown is the source of truth. The SQLite index is disposable and regenerated; never treat it as authoritative, never commit it.
2. Never hand-edit generated views. JOURNAL.md and themes/*.md in a managed journal are regenerated by refresh_views(). Changes go in entry files; views follow.
3. No data loss in intake/migration paths. Originals move to attic/, never deleted. Any new destructive-looking operation must preserve a recoverable copy and be covered by a test proving it.
4. Indexed-mode journals are read-only. Never restructure or write to a source configured with mode = "indexed".
5. Staging is the user's alone. Never run or suggest git add, git rm --cached, or git restore --staged — staging the index is the user's job, period. Claude may git commit and git push, but only with the user's explicit permission in the moment (never unprompted); commit what the user has already staged, don't stage more. Otherwise, present what changed (a file list or diff) and stop.

Working in This Repo

• Use the project venv. Prefer the make targets (they pin to .venv/bin and match CI): make test, make check, make lint-fix. Direct equivalents: .venv/bin/pytest -q, .venv/bin/ai-journal-mcp .... Setup: ./scripts/setup.sh. Full guide in docs/DEVELOPMENT.md.
• Before declaring work done, run make check (lint + format-check + type-check + docs lint + full suite with coverage; the docs lint needs Node/npm). It must be green.
• No warning creep. Every surfaced finding — from a review, a linter, or CI annotations — reaches a terminal state: fixed with a test, or recorded as a deliberate cut in ARCHITECTURE_DECISIONS.md ("Known limitations"). Never relay a capped/summarized review without expanding its cut list, and never leave "known minor issues" floating in conversation or commit messages as the only record.
• Ruff is the single linter/formatter and mypy the type authority; all tool config lives in pyproject.toml. Don't add competing config files.
• New behavior requires tests. Test data is fixture-based, not inline:
  • Formats/parsing → drop a real sample under tests/fixtures/ and let parametrize pick it up (parser changes must add a fixture reproducing the real-world format that motivated them — see tests/fixtures/parser/README.md).
  • Pure logic → table-driven via @pytest.mark.parametrize.
  • Filesystem behavior → the make_journal factory fixture in tests/conftest.py, not ad-hoc inline file-writing.
• The MCP server (server.py) is a thin layer; logic belongs in the library modules so it stays testable without an MCP client.
• The user's live journals are configured in ~/.config/ai-journal-mcp/journals.toml. Do not run migrate --apply or bulk-edit scripts against them without an explicit request and a fresh backup.