feat: Improve documentation and integrate mise

This commit introduces a comprehensive documentation system and integrates `mise` for a streamlined development environment.

Key changes include:
- A new `docs/` directory with detailed guides for Spendee, Firestore, MCP, testing, and project scripts.
- A hierarchical `agents.md` structure for AI-specific instructions, following the Docs/Agents split policy.
- A revamped `README.md` with separate sections for users and developers, and updated setup instructions.
- A `.mise.toml` file to manage Python, jq, and the Bitwarden CLI, simplifying environment setup.

Author: google-labs-jules[bot]

README.md

@@ -1,40 +1,51 @@
-# Spendee
+# Spendee Python Client
 
 This is a Python client for interfacing with the wonderful [Spendee app](https://www.spendee.com/).
 
 The codebase was forked from [dionysio/spendee](https://github.com/dionysio/spendee) (many thanks! <3) in 2025, which was authored in 2019-2020 and archived since then.
 
-About Spendee:
-> Spendee.com is a budget and expense tracker application to manage personal finances. It allows users to connect bank accounts, e-wallets, and crypto wallets to get an aggregated overview of their financial situation. The app helps users organize and analyze spending through automatic transaction categorization, visually appealing graphs, and insights.
+## ⚠️ Warning
 
-# Warning
+This is a work in progress and is not recommended for general use yet. The original Spendee API is undocumented, and while this client works at the time of writing, it might stop working at any time. The author is not associated with Spendee in any way.
 
-No guarantees are provided here. If you wanna use it, go for it, but do know that the original API is undocumented and while it works at the time of writing, it might stop at any time. I'm not associated with Spendee in any way.
+---
 
-## Development setup
+## For Users
 
-To set up a development environment (only linux is documented):
+*This section is for people who want to use the `spendee-python-client` library in their own projects.*
 
-1. Ensure you have Python 3.11+ installed.
-2. Setup the virtual environment:
+_(Coming soon)_
+
+---
+
+## For Developers & Contributors
+
+*This section is for people who want to contribute to the development of this library.*
+
+### Development Environment Setup
+
+This project uses [mise](https://mise.jdx.dev/) to manage the development environment.
+
+1.  **Install `mise`**: Follow the [official installation instructions](https://mise.jdx.dev/getting-started.html#installing-mise-cli) to install `mise` on your system.
+
+2.  **Activate `mise`**: Activate `mise` in your shell by following the instructions for your shell in the [official documentation](https://mise.jdx.dev/getting-started.html#activate-mise).
+
+3.  **Install Tools**: Once `mise` is activated, navigate to the project's root directory and run `mise install` to install the required tools.
+
+4.  **Set Credentials**: Create a `.env` file in the project root and add your Spendee credentials:
+    ```bash
+    echo 'EMAIL=<your-email>' > .env
+    echo 'PASSWORD=<your-password>' >> .env
+    ```
+
+5.  **Run**: You can now run the `run.py` script to experiment with the library:
     ```bash
-    # Create a virtual environment
-    python3 -m venv .venv
-    # Activate the virtual environment
-    source .venv/bin/activate
-    # Install dependencies
-    pip install -r requirements.txt
+    python run.py
     ```
-3. Set credentials in a newly created `.env` file.
-   ```bash
-   echo 'EMAIL=<email>' > .env
-   echo 'PASSWORD=<passwrod' >> .env
-   ```
-4. Adapt `run.py` for your experiment and execute.
 
-## Backstory and roadmap
+### Backstory and Roadmap
 
-As I started to use the forked repo in 2025, the fetched data from the REST API was outdated by multiple days compared to what is visible on connected Bank accounts and the online webpage.
+As the forked repo was started to be used in 2025, the fetched data from the REST API was outdated by multiple days compared to what is visible on connected Bank accounts and the online webpage.
 
 In the interim time since the original author implemented the REST API calls in 2020, Spendee most possibly migrated to another architecture. Based on browser debugging the new setup relies on Google firestore.
 
@@ -44,8 +55,6 @@ Next step will be to abstract away the most common operations.
 
 After that groundwork, the plan is to implement an MCP server enabling AI agent collaboration to have smarter categorization and conversational exploration of spending habits.
 
-Until that last milestone this project is not recommended for usage.
-
-## Contributing
+### Contributing
 
 If you can improve anything in this repo, feel free to add a pull request or add an issue!

agents.md

@@ -0,0 +1,45 @@
+# Agents Guide (Central)
+
+## Overview
+This document provides AI coding assistants with essential context for working with the spendee-python-client project.
+
+## Development Environment Setup
+This project uses [mise](https://mise.jdx.dev/) to manage the development environment. To set up your environment, follow these steps:
+
+1.  **Install `mise`**: If you don't have `mise` installed, you can install it by running `curl https://mise.run | sh`.
+2.  **Activate `mise`**: Activate `mise` in your shell by running `eval "$(~/.local/bin/mise activate bash)"`.
+3.  **Install Tools**: Navigate to the project's root directory and run `mise install`. This will install the tools defined in the `.mise.toml` file.
+
+For more detailed instructions, please refer to the [environment setup documentation](docs/environment.md).
+
+## 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/environment.md

@@ -0,0 +1,20 @@
+# Environment Setup
+
+This project uses [mise](https://mise.jdx.dev/) to manage the development environment. `mise` is a tool that helps you manage your development tools and environment variables.
+
+## Getting Started
+
+1.  **Install `mise`**: Follow the [official installation instructions](https://mise.jdx.dev/getting-started.html#installing-mise-cli) to install `mise` on your system.
+
+2.  **Activate `mise`**: Activate `mise` in your shell by following the instructions for your shell in the [official documentation](https://mise.jdx.dev/getting-started.html#activate-mise).
+
+3.  **Install Tools**: Once `mise` is activated, navigate to the project's root directory and run the following command to install the tools defined in the `.mise.toml` file:
+    ```bash
+    mise install
+    ```
+
+## Tools
+This project uses the following tools, which are managed by `mise`:
+*   **Python 3.11**
+*   **jq**: A command-line JSON processor.
+*   **Bitwarden CLI**: The command-line interface for Bitwarden.

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 `spendee/agents.md`.

docs/mcp.md

@@ -0,0 +1,23 @@
+# MCP (Model Context Protocol)
+
+## High-Level Overview
+MCP (Model Context Protocol) is an open-source standard for connecting AI applications to external systems. Think of it like a USB-C port for AI applications. Just as USB-C provides a standardized way to connect electronic devices, MCP provides a standardized way to connect AI applications to external systems like data sources, tools, and workflows.
+
+## Key Concepts
+*   **Servers:** Expose data and tools to AI applications.
+*   **Clients:** Connect to MCP servers to access data and tools.
+*   **Transports:** The underlying communication mechanism between clients and servers.
+
+## MCP Inspector
+The [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector) is an interactive developer tool for testing and debugging MCP servers. It allows you to:
+*   Inspect available resources, prompts, and tools.
+*   Test prompt generation and tool execution.
+*   View server logs and notifications.
+
+The `inspect2.sh` script in this repository is designed to help you run the MCP Inspector.
+
+## Further Reading
+For a deeper understanding of MCP, please refer to the [official documentation](https://modelcontextprotocol.io/docs/getting-started/intro).
+
+---
+For implementation details, see `mcp/agents.md`.

docs/scripts.md

@@ -0,0 +1,16 @@
+# Scripts and Dockerfile
+
+This page provides a brief overview of the scripts and the Dockerfile in this repository.
+
+## Scripts
+
+*   **`build.sh`**: Builds the Docker image for the MCP server and pushes it to a local registry.
+*   **`inspect.sh`**: A development script that sets up a Python virtual environment and executes the `spendee_mcp.py` script.
+*   **`inspect2.sh`**: Manages the MCP inspector tool, including cloning the repository, building the Docker image, and running the container.
+*   **`run-mcp.sh`**: Activates the Python virtual environment, loads environment variables, and executes the `spendee_mcp.py` script.
+*   **`run.py`**: A script for manual testing and interaction with the `SpendeeApi` and `SpendeeFirestore` classes. It's useful for debugging and experimentation.
+*   **`run_tests.sh`**: The test runner script. It checks for a `.env` file and then executes the test suite using `pytest`.
+*   **`re-deploy.sh`**: This script was requested for documentation but does not exist in the repository.
+
+## Dockerfile
+The `Dockerfile` sets up a Python 3.11 environment, installs dependencies from `requirements.txt`, copies the application code, and defines the entry point to run the MCP server.

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`.

mcp/agents.md

@@ -0,0 +1,16 @@
+# MCP Agent Guide
+
+This document provides AI coding assistants with essential context for working with the MCP server.
+
+## Key Files
+*   **`spendee/spendee_mcp.py`**: This file contains the implementation of the MCP server. It uses the `SpendeeFirestore` class to interact with Spendee.
+*   **`run-mcp.sh`**: This script is used to run the MCP server.
+*   **`inspect.sh`**: This script is a development script that sets up a Python virtual environment and executes the `spendee_mcp.py` script.
+*   **`inspect2.sh`**: This script is used to run the MCP Inspector, which is a tool for debugging MCP servers.
+
+## How to Work with the MCP Server
+When working with the MCP server, you will primarily be modifying the `spendee/spendee_mcp.py` file. Here are some common tasks:
+*   **Adding New Endpoints**: Add new methods to the `SpendeeMcp` class to expose new functionality.
+*   **Modifying Existing Endpoints**: Modify the existing methods in the `SpendeeMcp` class to change their behavior.
+*   **Running the Server**: Use the `run-mcp.sh` script to run the MCP server.
+*   **Debugging the Server**: Use the `inspect2.sh` script to run the MCP Inspector and debug the server.

mise.toml

@@ -0,0 +1,7 @@
+[tools]
+python = "3.11"
+jq = "latest"
+bws = "npm:@bitwarden/cli"
+
+[env]
+BWS_ACCESS_TOKEN = { source = "bws", secret = "BWS_ACCESS_TOKEN" }