feat: Add documentation for AI agents

This commit introduces a documentation framework to improve the usability of the repository for AI agents.

It adds:
- A root agents.md file with an overview, secret management instructions, and documentation policies.
- A docs/ directory with high-level wiki pages for Spendee, Firestore, MCP, and Testing.

Author: google-labs-jules[bot]

agents.md

@@ -0,0 +1,39 @@
+# Agents Guide (Central)
+
+## Overview
+This document provides AI coding assistants with essential context for working with the spendee-python-client project.
+
+## Development Environment Setup
+Please refer to the README.md for instructions on setting up the development environment.
+
+## Secrets Management
+We use Bitwarden for managing secrets. To access secrets, you will need the `BWS_ACCESS_TOKEN` environment variable set. You can then use the `bws` CLI to fetch secrets.
+
+**Example: Get a specific secret by key**
+```bash
+bws secret list | jq -r '.[] | select(.key == "spendee-password") | .value'
+```
+
+**Example: List all secret keys**
+```bash
+bws secret list | jq -r '.[] | .key'
+```
+
+## Living Documentation
+Important: The `agents.md` files are living documentation that should be updated alongside code changes. When implementing modifications:
+
+*   **Update Relevant Agent Files:** Consider which `agents.md` files need updates when making changes. Avoid adding to the root agents.md file and use dedicated directory related agents.md. Only add the the root, when it is really globally applicable, otherwise just reference there.
+*   **Keep Implementation Details Current:** Ensure commands, file paths, and procedures reflect the current state
+*   **Maintain Cross-References:** Update links between agent files and documentation
+*   **File References Only:** Never quote file content in agent files - only reference files by path
+*   **Consistency:** Ensure terminology and patterns remain consistent across all agent files
+
+## Docs/Agents split policy
+*   **Human docs (docs/**):** "What/Why"—architecture, domain flows, decisions, onboarding narratives, high-level troubleshooting flows.
+*   **Agents (`agents.md` files):** "How"—exact files to touch, commands, env/secrets guidance, gotchas, safe-change checklists, Cursor-ready prompts.
+
+Each agent file starts with a "Read the overview" links block to the relevant `docs/**` pages.
+
+Each relevant `docs/**` page gets a small footer: "For implementation details, see `<path>/agents.md`".
+
+Reduce code/text duplication as much as possible across twin docs and agents files.

docs/firestore.md

@@ -0,0 +1,31 @@
+# Firestore
+
+## High-Level Overview
+Firestore is a NoSQL document database from Google Firebase. It is used in this project to store and sync data in real-time.
+
+## Focused Examples
+Here's a basic example of how we interact with Firestore:
+
+```python
+from google.cloud import firestore
+
+# Initialize the client
+db = firestore.Client()
+
+# Get a reference to a document
+doc_ref = db.collection(u'users').document(u'alovelace')
+
+# Set data
+doc_ref.set({
+    u'first': u'Ada',
+    u'last': u'Lovelace',
+    u'born': 1815
+})
+```
+
+## Pointers
+*   [Official Firestore Documentation](https://firebase.google.com/docs/firestore)
+*   [Python Client Library Documentation](https://googleapis.dev/python/firestore/latest/index.html)
+
+---
+For implementation details, see `firestore/agents.md`.

docs/mcp.md

@@ -0,0 +1,18 @@
+# MCP (Master Control Program)
+
+## High-Level Overview
+MCP is the central orchestration component of this project. It is responsible for coordinating data flows between different services.
+
+## Focused Examples
+MCP is primarily configured through YAML files. Here's a conceptual example of a task definition:
+
+```yaml
+tasks:
+  - name: sync-spendee-to-firestore
+    source: spendee
+    destination: firestore
+    schedule: "0 * * * *"
+```
+
+---
+For implementation details, see `mcp/agents.md`.

docs/spendee.md

@@ -0,0 +1,13 @@
+# Spendee
+
+## What it is
+Spendee is a personal finance application that helps users track their expenses and income. This client library provides a Python interface to the Spendee API.
+
+## Core Concepts
+*   **Wallets:** Wallets represent your accounts (e.g., bank account, cash).
+*   **Transactions:** Transactions are individual expenses or incomes.
+*   **Categories:** Categories help you classify your transactions (e.g., food, transportation).
+*   **Labels:** Labels provide an additional way to organize your transactions.
+
+---
+For implementation details, see `spendee/agents.md`.

docs/testing.md

@@ -0,0 +1,13 @@
+# Testing
+
+## Overview
+This project uses a combination of unit tests and integration tests to ensure code quality. We use `pytest` as our primary testing framework.
+
+## MCP Testing
+MCP tests are located in the `tests/mcp` directory. These tests focus on verifying the logic of the orchestration tasks.
+
+## Spendee Firestore Testing
+Spendee Firestore tests are located in the `tests/spendee` directory. These tests focus on verifying the interaction between the Spendee client and the Firestore database.
+
+---
+For implementation details, see `tests/agents.md`.