diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..8633531
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,32 @@
+# AGENTS.md
+
+## Repo Facts
+
+- **Single-page app**: The entire dashboard is self-contained in `src/pages/index.astro` (~360 lines). It does not meaningfully use `Layout.astro` or `Welcome.astro` — those are leftover starter code and can be ignored or removed.
+- **Bun** is the package manager (lockfile: `bun.lock`). Use `bun install` / `bun dev` / `bun build`.
+- **No lint, test, or typecheck scripts** are defined in `package.json`. `tsconfig.json` extends `astro/tsconfigs/strict`.
+
+## Token & API
+
+- Dashboard fetches from a **hardcoded API base URL**: `https://bitfreedom.net/code/api/v1` (see `src/pages/index.astro:108`).
+- Access token is passed as a query param: `?access_token=<token>&since=<ISO>`.
+- Token is **injected at build time** via Vite `define` in `astro.config.mjs` (`ACCESS_TOKEN` → `import.meta.env.PUBLIC_ACCESS_TOKEN`).
+- Set it in `.env` as `PUBLIC_ACCESS_TOKEN=...`. `.env` is gitignored.
+- For deployments, the hosting platform must provide `PUBLIC_ACCESS_TOKEN` as a build env var.
+- To change the API endpoint or token mechanism, edit `src/pages/index.astro`.
+
+## Commands
+
+```
+bun install       # install deps
+bun dev           # dev server at localhost:4321
+bun build         # static output → dist/
+bun preview       # serve dist/ locally
+```
+
+## Structure Notes
+
+- `src/pages/index.astro` — the only meaningful page. Inline styles, inline JS, ApexCharts via CDN.
+- `src/layouts/Layout.astro` and `src/components/Welcome.astro` — unused starter code.
+- `public/` — only `favicon.ico` and `favicon.svg`.
+- `.playwright-mcp/` — contains Playwright MCP artifacts (screenshots, page yamls); not part of the app.
diff --git a/README.md b/README.md
index b6de9b9..f0bf0df 100644
--- a/README.md
+++ b/README.md
@@ -1,46 +1,101 @@
-# Astro Starter Kit: Basics
+# Time Tracking Dashboard
+
+A real-time dashboard built with [Astro](https://astro.build) that visualizes time tracking data from a Bitfreedom code API. Displays time worked across issues, pull requests, and date ranges using interactive ApexCharts.
+
+## Features
+
+- **Summary stats**: Time worked today, this week, and this month
+- **Weekly area chart**: Hours tracked over the last 14 days
+- **Monthly area chart**: Hours tracked over the last 30 days
+- **Issue breakdown**: Horizontal bar chart of time spent by issue
+- **PR breakdown**: Horizontal bar chart of time spent by pull request
+- **Distribution donut**: Ratio of time on issues vs. pull requests
+- **Dark theme**: Purple-accented responsive UI
+
+## Tech Stack
+
+- [Astro](https://astro.build) — static site framework
+- [ApexCharts](https://apexcharts.com) — interactive charts
+- [Node.js](https://nodejs.org) ≥ 22.12.0
+- [Bun](https://bun.sh) — package manager
+
+## Getting Started
+
+### Prerequisites
+
+- Node.js ≥ 22.12.0
+- Bun
+- An `ACCESS_TOKEN` for the Bitfreedom API
+
+### Install
 
 ```sh
-bun create astro@latest -- --template basics
+bun install
 ```
 
-> 🧑‍🚀 **Seasoned astronaut?** Delete this file. Have fun!
+### Environment
 
-## 🚀 Project Structure
+Copy the access token into the environment. Create a `.env` file at the project root:
 
-Inside of your Astro project, you'll see the following folders and files:
-
-```text
-/
-├── public/
-│   └── favicon.svg
-├── src
-│   ├── assets
-│   │   └── astro.svg
-│   ├── components
-│   │   └── Welcome.astro
-│   ├── layouts
-│   │   └── Layout.astro
-│   └── pages
-│       └── index.astro
-└── package.json
+```
+PUBLIC_ACCESS_TOKEN=your_token_here
 ```
 
-To learn more about the folder structure of an Astro project, refer to [our guide on project structure](https://docs.astro.build/en/basics/project-structure/).
+The token is injected at build time via Vite's `define` config in `astro.config.mjs`.
 
-## 🧞 Commands
+### Development
 
-All commands are run from the root of the project, from a terminal:
+```sh
+bun dev
+```
 
-| Command                   | Action                                           |
-| :------------------------ | :----------------------------------------------- |
-| `bun install`             | Installs dependencies                            |
-| `bun dev`             | Starts local dev server at `localhost:4321`      |
-| `bun build`           | Build your production site to `./dist/`          |
-| `bun preview`         | Preview your build locally, before deploying     |
-| `bun astro ...`       | Run CLI commands like `astro add`, `astro check` |
-| `bun astro -- --help` | Get help using the Astro CLI                     |
+Starts the local dev server at `localhost:4321`.
 
-## 👀 Want to learn more?
+### Build
 
-Feel free to check [our documentation](https://docs.astro.build) or jump into our [Discord server](https://astro.build/chat).
+```sh
+bun build
+```
+
+Produces a static site in `./dist/`.
+
+### Preview
+
+```sh
+bun preview
+```
+
+Serves the built output locally for a pre-deployment check.
+
+## Project Structure
+
+```
+├── astro.config.mjs      # Astro + Vite config (injects ACCESS_TOKEN)
+├── package.json          # Dependencies: astro, apexcharts
+├── tsconfig.json
+├── .env                  # Environment variables (not committed)
+├── public/               # Static assets
+├── src/
+│   ├── assets/           # SVG backgrounds, icons
+│   ├── components/
+│   │   └── Welcome.astro # Astro starter component (unused by dashboard)
+│   ├── layouts/
+│   │   └── Layout.astro  # Base layout template
+│   └── pages/
+│       └── index.astro   # Dashboard page (self-contained app)
+└── dist/                 # Built output
+```
+
+## API
+
+The dashboard fetches time tracking data from:
+
+```
+https://bitfreedom.net/code/api/v1/user/times?access_token=<token>&since=<ISO-date>
+```
+
+The `since` parameter defaults to the start of the current week (Monday). The API returns time entries with `created`, `time` (in seconds), and optional `issue` objects containing `id`, `number`, `title`, and `pull_request` flags.
+
+## Deployment
+
+Since `bun build` outputs a static site to `./dist/`, the dashboard can be deployed to any static hosting service (Netlify, Vercel, GitHub Pages, etc.). Make sure the `PUBLIC_ACCESS_TOKEN` environment variable is configured in your hosting platform.