harvask-cli 0.1.0

package/skills/harvask/GEMINI.md

@@ -0,0 +1,131 @@
+<!-- Generated from skills/harvask/SKILL.md by scripts/gen-agent-docs.mjs. Edit that file, then run `npm run gen:agents`. Do not edit skills/harvask/GEMINI.md by hand. -->
+
+# harvask CLI
+
+`harvask` is a command-line client for a harvask tenant, designed for coding
+agents: output is JSON by default and errors are structured as
+`Error / Why / Hint`.
+
+## First: authenticate
+
+Login is browser-based (no password typed into the CLI):
+
+```
+harvask login --tenant <tenant-domain>              # opens browser, approve, done (loopback)
+harvask login --tenant <tenant-domain> --no-browser # print URL, approve, paste the code (remote/headless)
+```
+
+You must be logged into the web app to approve. Tokens are stored per tenant
+under your OS config dir (mode 0600). Check status with `harvask whoami`.
+Log out with `harvask logout`.
+
+If a command fails with an auth error (exit code 3), run `harvask login` again.
+
+## Core workflow: discover → fetch → act
+
+1. **discover** the target
+   ```
+   harvask project list
+   harvask issue search -p PRJ "login bug"
+   ```
+2. **fetch** details
+   ```
+   harvask issue show -p PRJ 1234 --comments
+   harvask wiki show -p PRJ --slug api-documentation
+   ```
+3. **act**
+   ```
+   harvask issue create -p PRJ --title "Fix login" --type bug --priority high
+   harvask issue status -p PRJ 1234 in_progress
+   harvask issue assign -p PRJ 1234 --assignee-id 42
+   ```
+
+## project key vs id
+
+- Humans know the **key** (e.g. `PRJ`); the API uses a numeric **id**.
+- Every project-scoped command accepts either via `-p, --project <key|id>`
+  (`-p PRJ` or `-p 5`). The CLI resolves keys to ids automatically.
+- For `issue show/update/status/assign`, the issue argument accepts a numeric id
+  or a key like `PRJ-12` (resolved via search).
+- New to a tenant? Start with `harvask project list`.
+
+## Reading output
+
+- Default output is pretty JSON.
+- `--data` prints only the payload (unwraps `{issues:[...]}` → the array).
+- `--raw` prints the unformatted response.
+- `--json` forces machine-readable JSON (no color), even in a terminal.
+- Results go to stdout; errors go to stderr.
+
+## Long input (Markdown / JSON)
+
+- `--content` accepts a literal string, `@file.md` (read a file), or `-` (stdin).
+  ```
+  harvask wiki create -p PRJ --title "Docs" --content @docs.md
+  harvask note create --content -    # read from stdin
+  ```
+- The `api` escape hatch accepts a JSON body the same way (`@body.json`, `-`).
+
+## Common errors and what to do
+
+- **exit 3 / 401** — token invalid or expired → `harvask login --tenant <domain>`.
+- **403 tenant_mismatch** — token is for another tenant → use `--profile <domain>`
+  or re-login against the correct tenant.
+- **403 not_project_member** — you are not a member of that project → pick a
+  project from `harvask project list` or ask an admin to add you.
+- **404** — wrong id/key → verify with `harvask project list` / `harvask issue search`.
+- **422** — validation: read `Why:` for the offending field
+  (e.g. `issue_type`/`priority` enums, `title` ≤ 255, wiki/note content ≤ 500000).
+
+## Escape hatch (anything not wrapped)
+
+`harvask api <method> <path> [json]` calls any tenant API endpoint directly,
+for anything not covered by a dedicated command. Relative paths are namespaced
+automatically; absolute URLs and `..` are rejected.
+
+```
+harvask api GET projects
+harvask api GET projects/5/issues?status=open
+harvask api POST notes '{"content":"hi","is_pinned":true}'
+harvask api POST projects/5/issues @issue.json
+```
+
+## Command summary
+
+```
+harvask login | logout | whoami
+
+# project-scoped (pass -p <key|id>)
+harvask project        list | show <key|id> | create | members list|add|remove <key|id>
+harvask issue          list | show | create | update | search | status | assign
+harvask issue comment      list | create
+harvask issue todo         list | show | create | update | delete
+harvask issue memory       list | show | create | update | delete
+harvask issue dependency   list | add | remove
+harvask issue bulk-create | bulk-update      (--items @file.json [--atomic])
+harvask wiki           list | show | create | update | search | history | delete | bulk-create | bulk-update
+harvask milestone      list | create | update
+harvask workflow       list | show | create | update
+harvask scheduled-task list | show | create | update
+harvask file           search | stats
+harvask storage        search | stats | upload | folder | move | download | content
+harvask preview-config show | update
+harvask site-credential                       # list browser credentials
+
+# personal / tenant-wide (no -p)
+harvask note        list | show | create | update | delete | search
+harvask calendar    list | show | create | update | delete
+harvask global-wiki list | show | create | update | search | delete | bulk-create | bulk-update
+harvask user        list | search
+harvask chat        history <chatId> | search <q> | list | thread <kind> <uuid>
+harvask attachment  upload | download <id>
+
+harvask api <method> <path> [json]            # escape hatch
+```
+
+Notes:
+- `personal-wiki` is intentionally not available via the CLI.
+- File/binary: `storage upload` / `attachment upload` take `--file <path>`;
+  `storage download` / `attachment download` save with `--out <path>`.
+
+Use `harvask <command> --help` for options, examples, and prerequisites.

package/skills/harvask/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: harvask
+description: Operate a harvask tenant (issues, wiki, projects, notes, milestones, calendar, files, storage, chat, workflows, and more) from the command line via the `harvask` CLI. Use when the user asks to read/create/update tenant resources in harvask.
+---
+
+# harvask CLI
+
+`harvask` is a command-line client for a harvask tenant, designed for coding
+agents: output is JSON by default and errors are structured as
+`Error / Why / Hint`.
+
+## First: authenticate
+
+Login is browser-based (no password typed into the CLI):
+
+```
+harvask login --tenant <tenant-domain>              # opens browser, approve, done (loopback)
+harvask login --tenant <tenant-domain> --no-browser # print URL, approve, paste the code (remote/headless)
+```
+
+You must be logged into the web app to approve. Tokens are stored per tenant
+under your OS config dir (mode 0600). Check status with `harvask whoami`.
+Log out with `harvask logout`.
+
+If a command fails with an auth error (exit code 3), run `harvask login` again.
+
+## Core workflow: discover → fetch → act
+
+1. **discover** the target
+   ```
+   harvask project list
+   harvask issue search -p PRJ "login bug"
+   ```
+2. **fetch** details
+   ```
+   harvask issue show -p PRJ 1234 --comments
+   harvask wiki show -p PRJ --slug api-documentation
+   ```
+3. **act**
+   ```
+   harvask issue create -p PRJ --title "Fix login" --type bug --priority high
+   harvask issue status -p PRJ 1234 in_progress
+   harvask issue assign -p PRJ 1234 --assignee-id 42
+   ```
+
+## project key vs id
+
+- Humans know the **key** (e.g. `PRJ`); the API uses a numeric **id**.
+- Every project-scoped command accepts either via `-p, --project <key|id>`
+  (`-p PRJ` or `-p 5`). The CLI resolves keys to ids automatically.
+- For `issue show/update/status/assign`, the issue argument accepts a numeric id
+  or a key like `PRJ-12` (resolved via search).
+- New to a tenant? Start with `harvask project list`.
+
+## Reading output
+
+- Default output is pretty JSON.
+- `--data` prints only the payload (unwraps `{issues:[...]}` → the array).
+- `--raw` prints the unformatted response.
+- `--json` forces machine-readable JSON (no color), even in a terminal.
+- Results go to stdout; errors go to stderr.
+
+## Long input (Markdown / JSON)
+
+- `--content` accepts a literal string, `@file.md` (read a file), or `-` (stdin).
+  ```
+  harvask wiki create -p PRJ --title "Docs" --content @docs.md
+  harvask note create --content -    # read from stdin
+  ```
+- The `api` escape hatch accepts a JSON body the same way (`@body.json`, `-`).
+
+## Common errors and what to do
+
+- **exit 3 / 401** — token invalid or expired → `harvask login --tenant <domain>`.
+- **403 tenant_mismatch** — token is for another tenant → use `--profile <domain>`
+  or re-login against the correct tenant.
+- **403 not_project_member** — you are not a member of that project → pick a
+  project from `harvask project list` or ask an admin to add you.
+- **404** — wrong id/key → verify with `harvask project list` / `harvask issue search`.
+- **422** — validation: read `Why:` for the offending field
+  (e.g. `issue_type`/`priority` enums, `title` ≤ 255, wiki/note content ≤ 500000).
+
+## Escape hatch (anything not wrapped)
+
+`harvask api <method> <path> [json]` calls any tenant API endpoint directly,
+for anything not covered by a dedicated command. Relative paths are namespaced
+automatically; absolute URLs and `..` are rejected.
+
+```
+harvask api GET projects
+harvask api GET projects/5/issues?status=open
+harvask api POST notes '{"content":"hi","is_pinned":true}'
+harvask api POST projects/5/issues @issue.json
+```
+
+## Command summary
+
+```
+harvask login | logout | whoami
+
+# project-scoped (pass -p <key|id>)
+harvask project        list | show <key|id> | create | members list|add|remove <key|id>
+harvask issue          list | show | create | update | search | status | assign
+harvask issue comment      list | create
+harvask issue todo         list | show | create | update | delete
+harvask issue memory       list | show | create | update | delete
+harvask issue dependency   list | add | remove
+harvask issue bulk-create | bulk-update      (--items @file.json [--atomic])
+harvask wiki           list | show | create | update | search | history | delete | bulk-create | bulk-update
+harvask milestone      list | create | update
+harvask workflow       list | show | create | update
+harvask scheduled-task list | show | create | update
+harvask file           search | stats
+harvask storage        search | stats | upload | folder | move | download | content
+harvask preview-config show | update
+harvask site-credential                       # list browser credentials
+
+# personal / tenant-wide (no -p)
+harvask note        list | show | create | update | delete | search
+harvask calendar    list | show | create | update | delete
+harvask global-wiki list | show | create | update | search | delete | bulk-create | bulk-update
+harvask user        list | search
+harvask chat        history <chatId> | search <q> | list | thread <kind> <uuid>
+harvask attachment  upload | download <id>
+
+harvask api <method> <path> [json]            # escape hatch
+```
+
+Notes:
+- `personal-wiki` is intentionally not available via the CLI.
+- File/binary: `storage upload` / `attachment upload` take `--file <path>`;
+  `storage download` / `attachment download` save with `--out <path>`.
+
+Use `harvask <command> --help` for options, examples, and prerequisites.