docs: Revert README.md to a previous version

This commit reverts the README.md file to the state it was in at commit 8908488, undoing the changes from the previous commit.

Author: google-labs-jules[bot]

README.md

@@ -1,4 +1,4 @@
-# Spendee
+# Spendee Python Client
 
 This is a Python client for interfacing with the wonderful [Spendee app](https://www.spendee.com/).
 
@@ -7,11 +7,13 @@ The codebase was forked from [dionysio/spendee](https://github.com/dionysio/spen
 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
 
-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.
+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.
 
-## Development setup
+---
+
+## For Users
 
 To set up a development environment (only linux is documented):
 
@@ -28,13 +30,29 @@ To set up a development environment (only linux is documented):
 3. Set credentials in a newly created `.env` file.
    ```bash
    echo 'EMAIL=<email>' > .env
-   echo 'PASSWORD=<passwrod' >> .env
+   echo 'PASSWORD=<password' >> .env
    ```
 4. Adapt `run.py` for your experiment and execute.
 
-## Backstory and roadmap
+---
+
+## For Developers & Contributors
+
+### 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.
 
-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.
+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. **Follow the User guide** above.
+
+### Backstory and Roadmap
+
+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 +62,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,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
+This project uses [mise](https://mise.jdx.dev/) to manage the development environment. For detailed instructions on how to set up the environment, 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,17 @@
+# 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 several tools that are managed by `mise`. For a complete and up-to-date list of these tools, please refer to the `.mise.toml` file in the root of the repository.

firestore-schema.md docs/firestore-schema.mdfirestore-schema.md renamed to docs/firestore-schema.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/firestore.md

@@ -0,0 +1,28 @@
+# 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.
+
+## Authentication and Authorization
+The MCP server in this project uses a simple bearer token authentication mechanism. It does not implement OAuth or any other complex authentication schemes.
+
+To authenticate with the server, you must provide a bearer token in the `Authorization` header of your requests. The server expects the token to be the value of the `MCP_TOKEN` environment variable.
+
+## 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 `spendee/agents.md`.

docs/mcp.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/scripts.md

@@ -0,0 +1,15 @@
+# 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 more details on the data model, please refer to the [Firestore Schema](firestore-schema.md).
+
+---
+For implementation details, see `spendee/agents.md`.

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

docs/testing.md

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