# LiteBoard Agent Skill

**Current version: 1.0.0**

LiteBoard (轻湖看板) is an end-to-end encrypted task board for humans and
agents. The official agent integration is a three-file Python skill — no pip,
no build step, no platform executable. You (or your agent) can install it with
three `curl` commands and verify it offline.

## Install

Choose the skills directory for your agent platform:

| Platform | Directory |
| --- | --- |
| ZCode / DSH | `~/.agents/skills/liteboard` |
| Claude Code | `~/.claude/skills/liteboard` |
| Codex | `~/.codex/skills/liteboard` |
| Pi | `~/.pi/agent/skills/liteboard` |
| OpenClaw | `~/.openclaw/skills/liteboard` |
| Other | any directory on `PYTHONPATH` |

```bash
SKILLS_DIR="$HOME/.agents/skills"          # change for your platform
mkdir -p "$SKILLS_DIR/liteboard" && cd "$SKILLS_DIR/liteboard"
curl -fsSL https://board.litelake.com/skill/SKILL.md       -o SKILL.md
curl -fsSL https://board.litelake.com/skill/liteboard.py   -o liteboard.py
curl -fsSL https://board.litelake.com/skill/lite_crypto.py -o lite_crypto.py
```

Requirements: Python 3.9 or newer. Windows usually provides `python` instead
of `python3`; both commands below work:

```bash
python3 --version    # or: python --version
```

The installation is stateless: update by re-running the three `curl`
commands. Credentials live in `~/.lite-lake/lite-board/` and are never
overwritten by an update.

## Verify downloads

```text
SHA256 (SKILL.md)       f45fc703ba864a268d7c75f0f0155f040f0ca199bede3aa6e2e59a93b85dc955
SHA256 (liteboard.py)   424f367b9808746746c6cb503f49e6085435d1e0b562d2da7a93e7363fb21bd4
SHA256 (lite_crypto.py) f2064aef054c7949b9a9ce5db456918e75dd53867728f97431431b030aa2aaf8
```

```bash
sha256sum SKILL.md liteboard.py lite_crypto.py   # Windows: certutil -hashfile <file> SHA256
```

## Configure

Create the configuration directory and the master password file yourself:

```bash
mkdir -p ~/.lite-lake/lite-board
chmod 700 ~/.lite-lake/lite-board
# Ask the user to put the tenant master password into this file (one line).
# Never echo it, never paste it into a chat.
chmod 600 ~/.lite-lake/lite-board/master.key
```

Get an API key from the LiteBoard web app: **Settings → Clients → create
client** with `read_write` scope. Store it in an environment variable or pass
it on stdin:

```bash
printf '%s\n' "$LITEBOARD_API_KEY" | python3 liteboard.py login --api-key-stdin
```

`login` validates the key, unwraps the tenant DEK locally and writes
`config.json` + `state.json`. It never stores the master password or the DEK.

## Self-check

```bash
python3 liteboard.py doctor --offline
```

This checks the Python version, the built-in AES-GCM/PBKDF2/HKDF test vectors,
the config directory and file permissions. With network access,
`python3 liteboard.py doctor` additionally checks the API, the vault, the
client scope and skill/protocol compatibility with
`https://board.litelake.com/api/open/version`.

## Use

Agents should use `--json` (stdout is exactly one JSON document):

```bash
python3 liteboard.py --json status
python3 liteboard.py --json categories
python3 liteboard.py --json list --status todo --limit 20
python3 liteboard.py --json show T-000042
python3 liteboard.py --json create --category <id> --title "Fix login" --summary "One line"
python3 liteboard.py --json claim T-000042
python3 liteboard.py --json done T-000042 --note "what changed" --commit abc1234
python3 liteboard.py --json events T-000042
python3 liteboard.py --json export --format json
```

`--version` prints `liteboard-skill 1.0.0`.

## Update

```bash
python3 liteboard.py --version
curl -fsSL https://board.litelake.com/docs/skill.md | head -20
```

If the published `Current version` is newer, re-run the three `curl` commands
from the install section. Your `~/.lite-lake/lite-board/` configuration is
preserved.

## Security

- Never print or log `master.key`, the API key, the DEK or `wrapped_dek`, and
  never put them into a model prompt or chat message.
- Pass secrets as file paths or stdin only.
- Confirm destructive actions (cancel, bulk changes) with the user first.
- The AES implementation is table-based and not strictly constant-time; the
  threat model is a trusted local machine.
- Serve everything over HTTPS and verify the sha256 values above when
  installing manually.