# Project pack: WeKan @ a463937

Facts about **WeKan** 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.

> WeKan is an open-source kanban board. You create boards with lists and cards, drag cards between lists, assign people, add due dates, checklists, labels and attachments, and keep it all on your own server. It suits a household, a club or a small team that wants Trello without a subscription.

## Version and source
- Repository: https://github.com/wekan/wekan
- Pinned commit: `a463937cce289b58024026916b9591a228a4b354`. 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/wekan/wekan/archive/a463937cce289b58024026916b9591a228a4b354.zip
- Official docs: https://github.com/wekan/wekan/wiki
- Licence: **MIT**. Free to use, change and share, even commercially. Keep the original copyright notice.

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

  ```sh
  git clone https://github.com/wekan/wekan bespoke-wekan
  cd bespoke-wekan
  git checkout --detach a463937cce289b58024026916b9591a228a4b354
  # Prepare development requirements and local configuration first.
  meteor npm install
  meteor run --settings ./settings.json
  ```

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 -O https://raw.githubusercontent.com/wekan/wekan/main/docker-compose.yml
  # edit ROOT_URL in the file to the address you will use, for example http://localhost:2000
  docker compose up -d
  ```

- Needs: Docker for a trial, Meteor and Node for development
- Develop: `meteor run --settings ./settings.json`
- Test: `npm test`
- Stack: javascript (Meteor, Blaze, Node.js). Difficulty for a non-developer with an AI: **advanced**. A large Meteor application with its own build tooling and many options. Board settings, templates and rules need no code; source changes need the Meteor toolchain.

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

## Customisation points (settings → extend → code)
- **board-setup** [settings]: Your own columns, labels and card fields. → `Board menu → Settings (lists, labels, swimlanes, custom fields)`
- **rules-and-templates** [settings]: Automation such as 'when moved to Done, add a label'. → `Board → Rules, Board templates`
- **import-export** [settings]: Move boards in from Trello or CSV and export your data. → `Add Board → Import, Board menu → Export`
- **api** [extend]: Create cards from scripts. → `openapi/ and api.py examples`
- **client-ui** [code]: New card layouts and screens. → `client/components/`
- **models** [code]: New card fields and data rules. → `models/`

## Must keep working
- Database migrations in migrations/.
- Permissions for board membership, organisations and teams.
- Import and export formats.

## Staying updatable
Use board settings, rules, templates and the API first. For code, keep changes in new components and avoid touching Meteor packages.

## Data, costs and safety
- Personal data: **yes**. Stored in: A FerretDB or MongoDB database plus an uploads store (Docker volumes). Back up the database and the attachments together.
- Service: Email (SMTP) (optional, usually free to a few dollars): Invitations and notifications.
- Setting `ROOT_URL`: The address people use to reach WeKan.
- Setting `MAIL_URL` (**secret**: the person enters it themselves, never in chat): SMTP connection string if you want email. Contains a password; never paste it into an AI chat.
- WeKan is a large application. Keep it updated and behind HTTPS.
- Set ROOT_URL correctly and review who can register accounts before exposing it.

---

# Customising WeKan

WeKan is a Meteor application. Do as much as you can with board settings, rules and templates before you touch the code.

## How the code is laid out

| You want to change… | Look in |
|---|---|
| Screens and card layouts | client/components/ |
| Data models | models/ |
| Server code and publications | server/ |
| Database migrations | migrations/ |
| Reusable libraries | imports/ and packages/ |
| API docs | openapi/ |
| Translations | imports/i18n/ and the language files |

## Use the gentlest change first

1. **Settings (no code):** board settings, labels, custom fields, rules and templates.
2. **Extend:** import, export, the REST API and webhooks.
3. **Code:** Meteor components and models.

## Recipes

- **New card field:** add it to the model in `models/cards.js`, then show it in the card details component under `client/components/cards`.
- **New rule action:** add it where rules are defined and wire it to the board's Rules menu.

## Running and checking your changes

- Run with `meteor run`, create a board, a list and a card, and move the card.
- `npm test` for the test suite you changed.
- Check two browsers see each other's changes live.

## Pitfalls

- Add translation keys for new text. WeKan supports many languages.
- Meteor versions matter. Use the version in `.meteor/release`.

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