# Stash for agents

Stash (https://stash.thisismydesign.io) is the user's personal notepad: boards of notes, lists and ideas. You keep it for them. When they mention something to remember, buy, do, plan or look at, file it on the right board; when they ask what is up, read the boards and tell them.

## Boards

A board is one row in `boards`: `title`, `kind`, `content`, `tags`, `pinned`, `archived_at`, `share_token`.

- `content` is the whole board as text. Read it, change it, write it back whole.
- `kind` is one of:
  - `todo` — a Markdown task list. Items are `- [ ] text`; nested items indent two spaces under their parent. Ticked items are `- [x]` and live under a `## Done` heading at the end; the app moves whole top-level items there when ticked and back when unticked. Open items stay above the heading. Headings and plain lines may group items.
  - `markdown` — free-form notes, rendered with GitHub-flavoured Markdown.
  - `html` — a complete document, rendered in a sandboxed iframe (scripts run, no access to the app). Inline styles and scripts, absolute URLs for images.
- `tags` is a list of short lower-case labels (for example `travel`, `home`, `cars`); the app colours and filters by them. Reuse what exists before inventing new ones: list the boards first.
- `pinned` boards sort first. `archived_at` hides a board from the main list; never delete a board the user did not ask to delete.
- `share_token` is set while the board is shared: anyone with the link `https://stash.thisismydesign.io/s/<share_token>` can read it. Only the sharing functions below change it. Share a board only when the user asks.

## Writing for the user

- Keep the user's words. They dictate, so a word may be misspelled or be a sound-alike of the one meant; carry it over as given unless the intent is clear, and ask when a different reading would change the board.
- Add to boards rather than rewriting them. New to-do items go at the end of the open list, or under the heading they belong to.
- When something is done, tick it (`- [x]`) and move the item under `## Done`.

## Access

- If the user gave you an agent key (they make them under Agent keys in their profile menu), exchange it for a session at `POST https://supabase-stash.tail927dd3.ts.net/functions/v1/stash/token` with header `Authorization: Bearer <key>`.
- If you stored a refresh token earlier, refresh the session: `POST https://supabase-stash.tail927dd3.ts.net/auth/v1/token?grant_type=refresh_token` with header `apikey: sb_publishable_izn0-4oG_cXSqA3wC_iX5i_PT2-WbZc` and JSON `{"refresh_token"}`. Each refresh returns a new refresh token; store it.
- Otherwise, sign the user up: ask for their email and whether they want to choose a password or have Stash make one, then `POST https://supabase-stash.tail927dd3.ts.net/functions/v1/stash/signup` with JSON `{"email", "password"}`; leave `password` out for Stash to make one, returned once in the response. Store the refresh token durably and tell the user where. Give the user their email and password for signing in on the site; there is no reset by email, so they should keep it in a password manager, and can change it under Settings → Password.

## API

Boards are read and written through the Supabase REST API at https://supabase-stash.tail927dd3.ts.net/rest/v1, described at https://supabase-stash.tail927dd3.ts.net/functions/v1/stash/rest-openapi.json. Every call sends `apikey: sb_publishable_izn0-4oG_cXSqA3wC_iX5i_PT2-WbZc` and `Authorization: Bearer <access_token>`.

- List: `GET https://supabase-stash.tail927dd3.ts.net/rest/v1/boards?select=id,title,kind,tags,pinned,archived_at,updated_at&order=pinned.desc,updated_at.desc`
- Read one: `GET https://supabase-stash.tail927dd3.ts.net/rest/v1/boards?id=eq.<id>&select=*`
- Create: `POST https://supabase-stash.tail927dd3.ts.net/rest/v1/boards` with JSON `{"title","kind","content","tags"}` and header `Prefer: return=representation`
- Change: `PATCH https://supabase-stash.tail927dd3.ts.net/rest/v1/boards?id=eq.<id>` with the fields that change
- Delete: `DELETE https://supabase-stash.tail927dd3.ts.net/rest/v1/boards?id=eq.<id>`
- Share: `POST https://supabase-stash.tail927dd3.ts.net/rest/v1/rpc/share_board` with JSON `{"board_id"}`; returns `[board]` with `share_token` filled in. Give the user the link `https://stash.thisismydesign.io/s/<share_token>`.
- Stop sharing: `POST https://supabase-stash.tail927dd3.ts.net/rest/v1/rpc/unshare_board` with JSON `{"board_id"}`; the link stops working.

Sessions and this document are described at https://supabase-stash.tail927dd3.ts.net/functions/v1/stash/openapi.json.