# Project pack: Blinko @ b2586d0

Facts about **Blinko** for an AI following the [BespokeAI handover guide](https://handoff.bespokeai.software/guide/v2.md). This pack is pinned to one version and never changes after publication.

> Blinko is a self-hosted note capture tool for fleeting ideas. You jot thoughts as cards, tag them, and later search by meaning using an AI model you choose, including local models. It also offers a daily review, a hub for sharing, and apps for desktop and phone.

## Version and source
- Repository: https://github.com/blinkospace/blinko
- Pinned commit: `b2586d03fddb796252f050a96922879bf4a41fad`. Use exactly this version.
- Fresh checkout: use the setup below in an empty folder. If you already have this exact source checked out, keep your branch and use the development command instead; do not clone again or reset local changes.
- Or download a zip: https://github.com/blinkospace/blinko/archive/b2586d03fddb796252f050a96922879bf4a41fad.zip
- Official docs: https://docs.blinko.space
- Licence: **GPL-3.0-only**. Free to use and change. If you share your changed version with other people (give them the code or app), you must share your source code under the same licence. Using it privately for yourself or your household has no extra obligations.

## Running the pinned source
- Fresh pinned-source setup (skip clone and checkout in an existing worktree):

  ```sh
  git clone https://github.com/blinkospace/blinko bespoke-blinko
  cd bespoke-blinko
  git checkout --detach b2586d03fddb796252f050a96922879bf4a41fad
  # Prepare development requirements and local configuration first.
  bun install
  cp .env.example .env
  bun run dev:backend
  bun run dev:frontend
  ```

The commands below are a starting point from the reviewed source. Prepare the listed tools, local configuration and companion services before starting the app. These instructions have not yet been validated in participant sessions.

### Separate trial of the current release
This tries an upstream release, which may differ from the pinned source above. It does not run your source changes. Use only sample data and a separate data directory or volume. Check the upstream documentation before running it.

  ```sh
  curl -fsSL https://raw.githubusercontent.com/blinkospace/blinko/main/install.sh | bash
  # read the script before running it. It starts Blinko with Docker on http://localhost:1111
  ```

- Needs: Docker for a trial, Bun and Postgres for development
- Develop: `bun run dev:backend  # and, in another terminal: bun run dev:frontend`
- Test: `bun run test`
- Build: `bun run build:web`
- Stack: typescript (React, Vite, Express, tRPC, Prisma, Tauri, Bun, Turborepo). Difficulty for a non-developer with an AI: **moderate**. A TypeScript monorepo with a React front end and an Express and Prisma back end. AI provider, tags and appearance are settings; new features touch both sides.

## The project's own AI instructions
Read these in the repository before changing code: `CLAUDE.md`.

## Customisation points (settings → extend → code)
- **ai-provider** [settings]: Choose a cloud or local model for search and tagging. → `Settings → AI (model, embedding and API address)`
- **tags-and-appearance** [settings]: Theme, language, tags and default note types. → `Settings → Basic, Theme`
- **integrations** [extend]: Import from other tools and trigger webhooks. → `Settings → Import / Hooks, plugin SDK in the repo`
- **backend-routes** [code]: New note fields and endpoints. → `server/ (tRPC routers) and prisma/`
- **frontend-cards** [code]: New card types, layouts and screens. → `app/src/`

## Must keep working
- Prisma migrations. Add new ones; never edit old ones.
- Login and the NEXTAUTH_SECRET handling.
- Note data export, so users can always get their notes out.

## Staying updatable
Use settings and webhooks first. Add new routers and components in new files so upstream updates merge cleanly.

## Data, costs and safety
- Personal data: **yes**. Stored in: Postgres database plus an uploads folder (Docker volumes). Your notes may be sent to the AI provider you configure. Use a local model to keep them on your machine.
- Service: AI model provider (OpenAI-compatible, Ollama and others) (optional, pay-per-use for cloud, free for local): AI search, tagging and summaries.
- Setting `DATABASE_URL` (**secret**: the person enters it themselves, never in chat): Postgres connection string. Contains a password.
- Setting `NEXTAUTH_SECRET` (**secret**: the person enters it themselves, never in chat): Random secret used to sign logins. Never paste it into an AI chat.
- Setting `NEXTAUTH_URL`: The address people use to reach Blinko.
- AI features send note text to your chosen provider. Use a local model for private notes.
- Keep NEXTAUTH_SECRET and database passwords out of Git and chats.

---

# Customising Blinko

Blinko is a Turborepo with a Vite and React app, an Express and tRPC server, and a Prisma schema.

## How the code is laid out

| You want to change… | Look in |
|---|---|
| Screens and cards | app/src/ |
| API routers and AI features | server/ |
| Database schema and migrations | prisma/ |
| Types shared by both sides | shared/ and blinko-types/ |
| Docker and deployment | dockerfile, docker-compose.yml, helm/ |

## Use the gentlest change first

1. **Settings (no code):** AI provider, theme, language, tags and webhooks.
2. **Extend:** import data from other tools, or use webhooks.
3. **Code:** new fields, card types and screens, in new files.

## Recipes

- **New field on a note:** add it to `prisma/schema.prisma`, run `bun run prisma:migrate:dev`, add it to the router in `server/`, then show it in `app/src/`.
- **Change how AI tags notes:** look in the AI service in `server/` and keep provider calls behind the existing interface.

## Running and checking your changes

- Run backend and frontend in two terminals with a local Postgres.
- Capture a note, edit it, delete it, then search for it.
- `bun run test` before you finish.

## Pitfalls

- Run `bun run prisma:generate` after schema changes.
- Never commit `.env`, uploads or database dumps.

---
Machine-readable: [bespoke.yaml](https://handoff.bespokeai.software/p/blinko/b2586d0/r2/bespoke.yaml) · Hosting options: [hosting.md](https://handoff.bespokeai.software/p/blinko/b2586d0/r2/hosting.md) · Agent skill: [SKILL.md](https://handoff.bespokeai.software/p/blinko/b2586d0/r2/SKILL.md)