YKanBan/USAGE.md

# YKanBan Usage

YKanBan is a local/offline kanban board. It works like Git in one respect: all data for a managed project lives in a `.ykanban` folder at the project root, so the board travels with the project folder.

## 1. Workspace

- A **workspace** is a folder that directly contains a `.ykanban` directory. Only the given folder is checked; parent folders are never searched.
- `.ykanban` contains `ykanban.db` (the SQLite database with the board, cards and tags) and `ykanban.lock` (the exclusive lock file).
- A workspace is opened by exactly one YKanBan instance at a time. Opening the same workspace a second time shows the lock-conflict page.

### Command line

```
ykanban <path>
```

- `<path>` is the workspace folder to open. A relative path is resolved against the current working directory.
- Exactly one argument is required. Starting without arguments, with more than one argument, with a blank argument, with an argument starting with `-` (any option form, `--help` included), or with a path that does not exist or is not a folder shows the argument error page.
- If the folder exists but has no `.ykanban`, the not-initialized page is shown with an **Initialize Workspace** button. Initializing creates the database and seeds the preset columns and tags in the current interface language.

## 2. Do not commit `.ykanban` to Git

`.ykanban` holds machine-local state and a lock file; it should not be committed. Add it to your **global** gitignore so it is ignored in every repository:

```
# ~/.gitignore_global  (or %USERPROFILE%\.gitignore_global on Windows)
.ykanban/
```

Then enable the global ignore file once:

```
git config --global core.excludesFile ~/.gitignore_global
```

## 3. Backing up and migrating a workspace

The database runs in SQLite WAL mode. A workspace is therefore **three files**, not one: `ykanban.db`, `ykanban.db-wal` and `ykanban.db-shm`.

To back up or move a workspace, copy **all three files together** while YKanBan is closed. Copying only `ykanban.db` can lose the most recent changes.

## 4. Search syntax

The board search runs only when you press the search button (or press Enter in the search box); there is no live search. A blank query shows everything. The clear button (×) empties the box and restores the full board.

Search keywords (`AND`, `OR`) and qualifier keys are fixed English grammar and are **never localized**.

### 4.1 Grammar

```
query     := orExpr
orExpr    := andExpr ( OR andExpr )*
andExpr   := operand ( (AND)? operand )*     // adjacent terms are an implicit AND
operand   := atom | '(' orExpr ')'
atom      := word | phrase | qualifier
qualifier := key ':' (word | phrase)
key       := tag | title | content | id | column
phrase    := '"' any text '"'                // escapes: \" to literal quote and \\ to literal backslash
```

### 4.2 Semantics

- `AND` (explicit or by adjacency) binds tighter than `OR`; parentheses force grouping.
- Only uppercase `AND` / `OR` are operators. Lowercase `and` / `or` are plain words. To search for the literal words `AND` or `OR`, quote them, for example `"AND"`.
- A bare word or phrase matches a **substring of the title OR the content**.
- `tag:NAME` matches a tag by its **exact** name.
- `column:TITLE` matches a column by its **exact** title.
- `title:TEXT` matches a substring of the card title, and `content:TEXT` matches a substring of the card content.
- `id:N` matches a card by its **exact** positive integer id; an optional leading `#` is allowed (`id:#61`).
- All matching is Unicode case-insensitive (both sides are case-folded before comparing).
- Quotes allow values with spaces, for example `tag:"release notes"` or `column:"In Progress"`.
- Inside a phrase, `\"` produces a literal quote and `\\` a literal backslash.

### 4.3 Strict validation

An invalid expression opens a modal error dialog and **does not run the search**. The error dialog is centered on the parent window; its text is a localized "query expression is invalid" message plus the parser's non-localized English detail. After closing it, the search box keeps what you typed and the board keeps the previous results.

The following are invalid:

- unbalanced parentheses, for example `(a` or `a)`;
- a dangling operator, for example `bug AND`;
- consecutive operators, for example `a AND OR b`;
- a qualifier without a value, for example `tag:`;
- a qualifier phrase separated from its key by whitespace, for example `tag: "x"` (write `tag:"x"` instead);
- an unterminated phrase, for example `"abc`;
- an empty phrase, for example `""`;
- a phrase glued to other text, for example `a"b"`;
- an invalid escape inside a phrase (a backslash not followed by `"` or `\`), for example `tag:"a\x"`;
- a bare backslash in a word, for example `a\b`;
- an unquoted qualifier value containing `:` or equal to `AND`/`OR`, for example `tag:a:b` (quote the value instead);
- an id value that is not an unquoted positive integer with an optional `#`, for example `id:0`, `id:-1` or `id:"1"`;
- an unknown qualifier key. Only `tag`, `title`, `content`, `id` and `column` are valid, and the key is case-sensitive, so `Tag:x` is an error. A colon not preceded by a valid key (for example `:foo` or `http://x`) is an error; quote such text to search for it literally.

## 5. Export

The **Export** button writes a human-readable Markdown snapshot of the whole board (columns, cards and the tag table) to a file you choose. The suggested file name and the timestamps in the document follow the current interface language. The export is read-only; there is no import.