Skip to content

docs(site): refresh reference documentation #314

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
version-1 merged 2 commits into from
Aug 14, 2026
Merged

docs(site): refresh reference documentation #314

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
daf1260
docs(site): refresh reference documentation
version-1 Aug 14, 2026
505404f
docs(site): clarify reference constraints
version-1 Aug 14, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 14 additions & 1 deletion docs/site/docs/reference/api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ sidebar_position: 2

# API

The issue-tracker is the user-facing Tasq API. It owns project, issue, comment, attachment, workflow, and summary data.
The issue-tracker is the user-facing Tasq API. It owns project, issue, artifact, comment, change-request, attachment, workflow, and summary data.

## Response Envelope

Expand Down Expand Up @@ -48,6 +48,11 @@ Error responses use:
| `GET` | `/api/v1/issues/{issueId}/comments` | List comments. |
| `POST` | `/api/v1/issues/{issueId}/comments` | Add a comment. |
| `PATCH` | `/api/v1/comments/{id}` | Update a comment. |
| `GET` | `/api/v1/issues/{issueId}/change-requests` | List change requests for an issue. |
| `POST` | `/api/v1/issues/{issueId}/change-requests` | Create an open change request. |
| `GET` | `/api/v1/change-requests/{id}` | Read a change request. |
| `PATCH` | `/api/v1/change-requests/{id}` | Edit the body while `open`, or perform an allowed status transition. |
| `POST` | `/api/v1/change-requests/{id}/cancel` | Cancel an open or in-progress change request. |
| `GET` | `/api/v1/attachments` | List attachments. |
| `POST` | `/api/v1/attachments` | Upload an attachment. |
| `GET` | `/api/v1/attachments/{id}/content` | Download attachment bytes. |
Expand All @@ -61,8 +66,16 @@ Issue listing supports filters for `states`, `project_id`, `project_ids`,
Comment listing supports `cursor` and `limit`. Attachment listing supports
`entity_type` and `entity_id`.

Change-request listing supports an optional `status` filter and `limit` from `1` to `100`, defaulting to `50`.

Issue responses always include an `artifacts` array, sorted by `type`, including `[]` when no artifacts exist. The initial `pull_request` artifact accepts only `data_value` on `PUT`; the server returns `type`, `data_type`, and `data_value`. `DELETE` returns an empty `204`. Invalid types or URLs return `400`; a missing issue or artifact returns `404`.

Change requests capture additional work for a later agent run. Creation sets the status to `open`. Allowed transitions are `open` to `in_progress` or `canceled`, and `in_progress` to `resolved` or `canceled`. Resolved and canceled requests are immutable. Cancellation is a state transition; there is no physical delete endpoint.

## Contract Sources

The [issue-tracker OpenAPI document](https://github.com/version-1/tasq/blob/main/docs/openapi/issue-tracker.yml) and [orchestrator OpenAPI document](https://github.com/version-1/tasq/blob/main/docs/openapi/orchestrator.yml) define request parameters, bodies, responses, and error status codes. This page is the concise endpoint and behavior reference.

## Attachments

Attachment uploads use multipart form data with `entity_type`, `entity_id`, and `file`. Supported image types are PNG, JPEG, GIF, and WebP up to 5 MiB.
Expand Down
29 changes: 27 additions & 2 deletions docs/site/docs/reference/cli-reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ sidebar_position: 1

# CLI Reference

`tq` is the command-line interface for issue management, project setup, workflow configuration, local services, logs, migrations, and the Web UI.
`tq` is the command-line interface for issue management, project setup, workflow configuration, raw API access, local services, logs, migrations, and the Web and terminal UIs.

## Global Form

Expand All @@ -31,7 +31,7 @@ API URL resolution order is `--api-url`, `TQ_API_URL`, `$TQ_HOME/system/state.js
| `tq issue update <id> [flags]` | Update issue fields. |
| `tq issue watch [--interval <duration>] [--seen-ttl <duration>] [--verbose]` | Poll ready issues and emit JSON event envelopes. |
| `tq issue close <id>` | Move an issue to `done`. |
| `tq issue cancel <id>` | Move an issue to `failed`. |
| `tq issue cancel <id>` | Move an issue to `cancelled`. |
| `tq issue ready <id>` | Move an issue to `ready`. |
| `tq issue draft <id>` | Move an issue to `backlog`. |
| `tq issue rename <id> <title>` | Update the title. |
Expand Down Expand Up @@ -88,12 +88,37 @@ Allowed comment types are `progress`, `blocker`, `handoff`, and `general`.
| `tq migrate down` | Roll back migrations. |
| `tq migrate status` | Show migration status. |
| `tq web` | Open the running Web UI. |
| `tq tui` | Open the experimental read-only terminal UI. Aliases: `tq console`, `tq c`. |
| `tq config` | Show build, home-directory, and resolved configuration information. |
| `tq version` | Print version information. |
| `tq update [-y] [--tag <tag>]` | Install a release, migrate databases, and restart services. |

Log services are `tracker` or `issue-tracker`, `orchestrator`, and `web`.

`tq tui [--orchestrator-url URL]` requires a terminal and supports only text output. It reads issues, comments, artifacts, and run state without sending mutation requests. Use `--orchestrator-url` to override orchestrator discovery from `state.json`.

`tq config` prints the version, build profile, `TQ_HOME` override, resolved home directory, configuration file path, and resolved values. It does not print the raw YAML. Use global `--output json` for scripts.

`tq update` prints the current and target versions, confirms that local services will stop and restart, installs the latest formal release by default, verifies the newly installed `tq version`, runs migrations, and starts services. `-y` skips the confirmation prompt. `--tag` installs a specific release or prerelease tag.

`tq update` is unavailable when the binary has a non-empty build profile such as `dev`, because generic release artifacts do not retain that profile.

For step-by-step examples and service interruption guidance, see
[Update Tasq](pathname:///guides/update-tasq).

## Raw API Command

Use `tq api` for an issue-tracker operation that has no typed command:

```sh
tq api GET /api/v1/issues --query states=ready
tq api POST /api/v1/issues --header 'X-Request-ID: local-123' --data @request.json
```

```text
tq api <method> <path> [--query key=value] [--header 'Name: value'] [--data value|@file|-]
```

The path must be an allowlisted, unencoded absolute `/api/v1/...` path. Complete URLs, fragments, dot segments, empty segments, and trailing slashes are rejected. `--query` and `--header` are repeatable. `--data` accepts a literal value, `@file`, or `-` for standard input and is available only for `POST`, `PUT`, and `PATCH`.

The command does not prompt before writes or deletes, does not follow redirects, and times out after 10 seconds. Response bytes are written unchanged, so global `--output` does not transform them. Exit status is `0` for HTTP `2xx`, `1` for HTTP or transport failures, and `2` for invalid usage, input, or a request outside the allowlist.
4 changes: 4 additions & 0 deletions docs/site/docs/reference/configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,8 @@ By default, `TQ_HOME` resolves to `~/.tasq`. For repository-local development, s
export TQ_HOME="$PWD/.tasq"
```

Development binaries may embed a lowercase build profile such as `dev`, which changes the default home to `~/.tasq-dev`. An explicit `TQ_HOME` always wins. All sibling executables must use the same profile so `tq`, issue-tracker, orchestrator, and Web UI discover the same state.

## Directory Layout

```text
Expand All @@ -34,6 +36,8 @@ $TQ_HOME/

`config/` is user-editable. `system/` is managed by Tasq processes.

Run `tq config` to inspect the version, build profile, `TQ_HOME` override, resolved home, configuration path, and resolved values. Use `tq --output json config` for machine-readable output.

## config.yaml

```yaml
Expand Down
6 changes: 6 additions & 0 deletions docs/site/docs/reference/schema.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@ Tasq validates entity data at the store layer on create and update operations. T
| Issue | `projectId`, `title` | title 1-500 chars, description max 10,000 chars, assignee max 200 chars, immutable project ownership |
| Artifact | `type`, `dataType`, `dataValue` | one per issue and type; initial type `pull_request` has data type `url`; URL is trimmed, absolute HTTP(S), host-required, userinfo-free, max 4,096 UTF-8 bytes |
| Comment | `issueId`, `author`, `body` | body 1-10,000 chars, type defaults to `general` |
| ChangeRequest | `issueId`, `author`, `body` | body 1-10,000 chars and editable only while `open`; status defaults to `open`; terminal requests are immutable |
| Attachment | `entityType`, `entityId`, `file` | image PNG/JPEG/GIF/WebP, max 5 MiB |
| Project | `key`, `name`, `location` | key format, name 1-200 chars, description max 10,000 chars, absolute location |
| ProjectWorkflow | `projectId`, `frontmatter`, `body`, `checksum` | one workflow override per project, checksum is SHA256 hex |
Expand All @@ -36,6 +37,7 @@ Tasq validates entity data at the store layer on create and update operations. T
| Queue status | `backlog`, `pending`, `queued`, `processing`, `completed`, `inactive` |
| Issue priority | `low`, `normal`, `high`, `urgent` |
| Comment type | `progress`, `blocker`, `handoff`, `general` |
| Change-request status | `open`, `in_progress`, `resolved`, `canceled` |
| Attachment entity type | `issue`, `comment` |
| Artifact type | `pull_request` |
| Artifact data type | `url` |
Expand All @@ -53,3 +55,7 @@ flowchart TD
```

Absolute path fields must start with `/`. Clients such as `tq project add` check local directory existence when they can access the target filesystem.

## State Transitions

Change requests allow `open` to `in_progress` or `canceled`, and `in_progress` to `resolved` or `canceled`. Resolving can record the orchestrator run and a result comment on the same issue. `resolved` and `canceled` are terminal states.
27 changes: 20 additions & 7 deletions docs/site/i18n/ja/docusaurus-plugin-content-docs/current/reference/api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,25 +4,25 @@ title: API
sidebar_position: 2
---

# API
# API リファレンス

issue-tracker は user-facing Tasq API です。project、issue、comment、attachment、workflow、summary data を所有します。
Issue Tracker は利用者向けの Tasq API です。プロジェクト、課題、Artifact、コメント、change request、添付ファイル、ワークフロー、サマリーのデータを所有します。

## Response Envelope
## レスポンス形式

success responses は次を使います。
成功時のレスポンスは次の形式です。

```json
{ "data": {}, "meta": {} }
```

error responses は次を使います。
エラー時のレスポンスは次の形式です。

```json
{ "error": { "code": "invalid_request", "message": "..." }, "meta": {} }
```

## Issue-Tracker Endpoints
## Issue Tracker エンドポイント

| Method | Path | Purpose |
| --- | --- | --- |
Expand All @@ -48,6 +48,11 @@ error responses は次を使います。
| `GET` | `/api/v1/issues/{issueId}/comments` | comments を list します。 |
| `POST` | `/api/v1/issues/{issueId}/comments` | comment を追加します。 |
| `PATCH` | `/api/v1/comments/{id}` | comment を更新します。 |
| `GET` | `/api/v1/issues/{issueId}/change-requests` | 課題の change request を一覧表示します。 |
| `POST` | `/api/v1/issues/{issueId}/change-requests` | `open` 状態の change request を作成します。 |
| `GET` | `/api/v1/change-requests/{id}` | change request を取得します。 |
| `PATCH` | `/api/v1/change-requests/{id}` | `open` の間に本文を編集するか、許可された状態遷移を行います。 |
| `POST` | `/api/v1/change-requests/{id}/cancel` | `open` または `in_progress` の change request を取り消します。 |
| `GET` | `/api/v1/attachments` | attachments を list します。 |
| `POST` | `/api/v1/attachments` | attachment を upload します。 |
| `GET` | `/api/v1/attachments/{id}/content` | attachment bytes を download します。 |
Expand All @@ -61,9 +66,17 @@ issue listing では `states`、`project_id`、`project_ids`、`priorities`、
comment listing は `cursor` と `limit` を受け付けます。attachment listing は
`entity_type` と `entity_id` を受け付けます。

change request の一覧取得では、任意の `status` フィルターと `1`〜`100` の `limit` を指定できます。`limit` の既定値は `50` です。

課題レスポンスには、Artifact がない場合も `[]` となる `artifacts` 配列が常に含まれ、`type` 昇順で返ります。初期の `pull_request` Artifact では、`PUT` に `data_value` だけを指定します。サーバーは `type`、`data_type`、`data_value` を返します。`DELETE` は本文のない `204` を返します。不正な type または URL は `400`、課題または Artifact が存在しない場合は `404` です。

## Attachments
change request は、後続のエージェント実行で対応する追加作業を記録します。作成時の状態は `open` です。許可される状態遷移は `open` から `in_progress` または `canceled`、`in_progress` から `resolved` または `canceled` です。`resolved` と `canceled` は変更できません。取り消しは状態遷移として扱われ、物理削除のエンドポイントはありません。

## コントラクトの参照先

[Issue Tracker の OpenAPI 文書](https://github.com/version-1/tasq/blob/main/docs/openapi/issue-tracker.yml)と [orchestrator の OpenAPI 文書](https://github.com/version-1/tasq/blob/main/docs/openapi/orchestrator.yml)が、リクエストパラメーター、本文、レスポンス、エラーステータスを定義します。このページはエンドポイントと動作の要約です。

## 添付ファイル

Attachment uploads は `entity_type`、`entity_id`、`file` を含む multipart form data を使います。supported image types は PNG、JPEG、GIF、WebP で、上限は 5 MiB です。

Expand Down
Loading
Loading