vikunja-agents/AGENT-ONBOARDING.md

# Vikunja access — agent onboarding prompt

Hand the block below to any agent that needs Vikunja access. It is written to be
pasted verbatim as a task prompt. Everything after the `---` is the prompt.

Before pasting, substitute:

- `<AGENT_NAME>` — the bot account for this harness, e.g. `bot-nullclaw`
- `<HARNESS>` — `claude-code`, `omp`, `picocode`, or `other`

---

## Task: configure your own Vikunja access

You are `<AGENT_NAME>`. Give yourself working access to Vikunja at
`https://todo.dominat.us`, then verify it and report what you can and cannot see.

### Facts you need

- The tooling is a public repo. Clone it on whatever machine you run on — no
  credentials needed, and standard-library Python only, so there is nothing to
  install:

  ```sh
  git clone https://git.dominat.us/oc/vikunja-agents.git ~/opt/vikunja-agents
  mkdir -p ~/.local/bin && ln -sf ~/opt/vikunja-agents/vk ~/.local/bin/vk
  ```

  It gives you `vk` (CLI), `vikunja_mcp.py` (MCP server, stdio) and
  `vkclient.py` (shared client). To update later: `git -C ~/opt/vikunja-agents pull`.
- On `reptar` it is already checked out at `/srv/pods/vikunja-agents/`; use that
  path instead of cloning again.
- Auth is a Vikunja **API token**, read from `~/.config/vikunja-agents/config.json`
  (mode 0600) or `$VIKUNJA_TOKEN`. Select an identity with `$VIKUNJA_PROFILE`.
- Your account must already exist. The normal shape is a **bot user**: a local
  account owned by a human, with no password of its own. If it does not exist,
  stop and ask — creating one is your owner's job (Vikunja UI: Settings → Bot
  Users). MAS/OIDC accounts cannot be used for this (see constraints).

### Step 1 — get your token (once)

**If your account is a bot user** (the normal case — it has an owner and no
password), you cannot mint your own token: token creation needs a password login
and bots have none. Your owner mints it for you, then hands it over out of band.
Store it without putting it in argv or shell history:

```sh
vk profile <AGENT_NAME> --username <AGENT_NAME> < /path/to/token-file
# or:  pbpaste | vk profile <AGENT_NAME> --username <AGENT_NAME>
```

`vk profile` verifies the token against the API before saving, so a bad paste
fails loudly instead of silently writing a dead profile. It lands in
`~/.config/vikunja-agents/config.json` at mode 0600.

If you have no token, stop and ask your owner for one. They create it from
Vikunja's UI (Settings → API tokens, issued for your bot) or with an
authenticated `PUT /api/v1/tokens` carrying `owner_id: <your user id>`.

**If your account is instead a plain user with a password** (legacy), you can
mint your own:

```sh
VIKUNJA_PASSWORD="$(cat ~/.config/vikunja-agents/<AGENT_NAME>.password)" \
  vk bootstrap --username <AGENT_NAME> --title "<HARNESS> ($(hostname))"
```

Either way: **never echo the token, paste it into a chat, or commit it.** It
expires in a year and cannot renew itself — renewal means asking your owner
again.

### Step 2 — register the MCP server for your harness

`claude-code`:

```sh
claude mcp add vikunja -e VIKUNJA_PROFILE=<AGENT_NAME> -- /srv/pods/vikunja-agents/vikunja_mcp.py
```

`omp` — add to `~/.omp/agent/mcp.json` (create it if absent):

```json
{
  "mcpServers": {
    "vikunja": {
      "type": "stdio",
      "command": "/srv/pods/vikunja-agents/vikunja_mcp.py",
      "env": { "VIKUNJA_PROFILE": "<AGENT_NAME>" }
    }
  }
}
```

`picocode` — add to `picocode.yaml`:

```yaml
mcp:
  vikunja:
    command: /srv/pods/vikunja-agents/vikunja_mcp.py
    env:
      VIKUNJA_PROFILE: <AGENT_NAME>
    auto_allow:
      - "^vikunja_list_"
      - "^vikunja_get_"
```

`other` — the server speaks MCP over stdio (JSON-RPC 2.0, newline-delimited).
Run `vikunja_mcp.py` with `VIKUNJA_PROFILE` set.

In every snippet above, use `/srv/pods/vikunja-agents/vikunja_mcp.py` on `reptar`
and `~/opt/vikunja-agents/vikunja_mcp.py` wherever you cloned it. If your
harness cannot speak MCP, skip this step and use the `vk` CLI instead; it covers
the same ground.

### Step 3 — verify, and do not skip this

```sh
vk whoami          # must print <AGENT_NAME>
vk projects        # the projects you can actually see
vk tasks --mine    # your queue
```

Then confirm the MCP path independently of the CLI — restart your harness if it
binds MCP servers at startup (claude-code does), and call `vikunja_list_projects`.
If the tool is missing, the registration did not take; if it errors, the token
did not take. These are different failures — do not report one as the other.

### Step 4 — report

State plainly:

1. Which projects you can see (likely only your own `Inbox` — see constraints).
2. Whether MCP tools are available, or whether you fell back to the CLI.
3. Anything you had to ask a human for.

### Constraints that will otherwise cost you an hour

- **A token cannot mint another token.** Vikunja excludes the `tokens` route
  group from anything an API token can be granted. For a bot user that means
  only your owner can issue or renew your token; you can never do it yourself,
  and there is no password you could use even if you wanted to.
- **You cannot ask the API who you are.** `/user` is unreachable with a token
  (`user_*` routes are excluded too). `vk whoami` reads the username from your
  config file. Do not try to fix a 401 on `/user` — it is expected.
- **You start with only your own Inbox.** A new account sees nothing else until a
  human shares projects with it. If `vk projects` shows one project, that is
  normal, not a broken token — say so and ask for the shares you need.
- **Assignment is dispatch.** Work reaches you by being assigned to
  `<AGENT_NAME>`. Use `vk tasks --mine`. Do not scrape other agents' queues.
- **Username lookup is project-scoped.** Resolving a username to an id uses
  `/projects/{id}/projectusers`; the instance-wide `/users` search is not
  grantable to tokens. You can only assign to users who can access that project.
- **Updates replace the whole task.** The client merges for you; if you call the
  API directly, read-modify-write or you will blank fields.
- **Link your work back.** Put `VK-<task id>` in commit messages, and
  `fixes VK-<id>` to close a task on push — a Gitea bridge posts the commit link
  onto the task. Without it a task says "done" but never says what changed.

### Rules

- One account per harness. Do not share a profile with another agent — separate
  accounts are what make the task history say who did what.
- Never print, log, or transmit the token or password. If you think one leaked,
  say so immediately; rotation needs a human.
- Comment on tasks when you finish work, find something that changes scope, or
  are blocked. Do not narrate routine steps.