# Bukumatter Agent Onboarding

This is an execution instruction for the Bukumatter AI agent integration version.

Do not summarize this document.
Do not explain the flow as a document.
Perform the onboarding flow below.

If the user only provides this URL, assume the user wants to start onboarding.
Your first response must be the pre-registration explanation.

## Rules

- Use the user's language.
- If the user writes in Japanese, speak Japanese.
- Do not call the registration API before explicit user consent.
- Do not ask for consent until after the full pre-registration explanation.
- Do not display the handle, password, or agent key in chat unless the user explicitly asks.
- Call `passcode` a password when speaking to the user.
- Save credentials to a local Markdown file after registration.
- Warn the user that the local file contains credentials.
- Folder creation is available after registration.
- Add Bookmark is available after registration.

## First Response

If the user writes in Japanese, send this message first:

```text
ブクマッターは、フォルダを作成してURLをブックマークとして追加できるサービスです。

ブクマッターのAIエージェント連携版では、私があなたの代わりに、ブックマーク用のフォルダ作成とブックマーク追加を行えるようになります。

登録を開始すると、AIエージェント用の新しいブクマッターユーザーが作成されます。既存のブクマッターアカウント、フォルダ、ブックマークには接続せず、変更もしません。

登録後には、AIエージェント連携版のAPIを利用するためのエージェントキーが発行されます。また、必要な場合にブクマッターのWebサイト版へログインするためのパスワードも発行されます。

パスワードとエージェントキーは認証情報です。慎重に扱う必要があります。

AIエージェント連携版のAPIで作成されるフォルダやブックマークは非公開です。このAPIから公開設定を変更することはできません。

また、ブクマッターは外部Webサイトの正確性や可用性を保証しません。

登録を開始してよいですか？ はい / いいえ
```

If the user writes in another language, provide the same meaning in that language and ask for explicit consent.

## Consent

Onboarding consent and registration consent are different.

A message that asks you to start, continue, read the URL again, or follow this onboarding flow is not registration consent.
Registration consent is valid only after you have sent the full pre-registration explanation and asked this exact question:

```text
登録を開始してよいですか？ はい / いいえ
```

Treat these Japanese replies as consent:

```text
はい
OK
進めて
登録して
```

If consent is unclear, ask once for clarification.
If the user refuses, stop.

## Registration API

After explicit consent only, call:

```text
POST https://agent-dev.bukumatter.com/api/register
```

No request body is required.

Expected success response:

```json
{
  "success": true,
  "handle": "xxxxxxxx",
  "passcode": "generated-password",
  "agentKey": "generated-agent-key"
}
```

`passcode` is the password.
`agentKey` is the credential for AI agent integration API access.

## Save Credentials

After successful registration, create or update:

```text
bukumatter-agent.local.md
```

Before writing it, tell the user:

```text
認証情報を bukumatter-agent.local.md に保存します。このファイルには認証情報が含まれるため、コミットしたり公開したりしないでください。
```

Use this file structure:

Copy this template exactly.
Only fill in `Handle`, `Password / パスワード`, and `Agent Key`.
Do not rename `Password / パスワード` to `Passcode`.
Do not use a table.
Do not add claims about unsupported features.

```text
# Bukumatter Agent Local Setup
# ブクマッター エージェント用ローカル設定

> WARNING / 警告
> This file contains credentials.
> Do not commit this file or share it publicly.
> このファイルには認証情報が含まれています。
> コミットしたり、公開したりしないでください。

## Service / サービス

API endpoint:
https://agent-dev.bukumatter.com

## Temporary Credentials / 暫定認証情報

Handle:
Password / パスワード:
Agent Key:

## Credential Handling / 認証情報の取り扱い

- Do not commit this file.
- Do not share this file publicly.
- このファイルをコミットしないでください。
- このファイルを公開しないでください。
- 必要な場合は、ハンドルとパスワードでブクマッターのWebサイト版にもログインできます。

## Visibility Policy / 公開設定

- Folders and bookmarks created through the AI agent integration API are private by default.
- Visibility cannot be changed through the AI agent integration API.
- AIエージェント連携版のAPIで作成されるフォルダやブックマークは、初期状態では非公開です。
- AIエージェント連携版のAPIから公開設定を変更することはできません。

## Agent Manifest / エージェントマニフェスト

Local manifest version:
2026-05-11.8

Latest manifest URL:
https://agent-dev.bukumatter.com/instructions/bukumatter-agent-manifest.md

- Use this local file first.
- Read the latest manifest only when the requested operation is not described here, an API call fails because the contract may have changed, or the user asks you to refresh the Bukumatter agent manifest.
- 通常はこのローカルファイルを先に参照してください。
- 必要な操作がこのファイルにない場合、API仕様が変わった可能性がある場合、またはユーザーが更新を依頼した場合だけ、最新のマニフェストを読んでください。

## Timestamp Display / 時刻表示

- When showing createdAt or updatedAt values, display the timezone explicitly.
- If using the stored ISO timestamp without conversion, label it as UTC.
- Do not present UTC timestamps as local time unless the user explicitly asks for a local timezone conversion.
- createdAt / updatedAt を表示する場合は、タイムゾーンを明示してください。
- 保存されたISO時刻を変換せずに使う場合は、UTCとして表示してください。
- ユーザーが明示的にローカルタイムゾーン変換を依頼しない限り、UTC時刻をローカル時刻のように表示しないでください。

## Available Actions / 利用可能な操作

### Create Folder / フォルダ作成

Status:
Available

What the agent can do:
Create a private folder in Bukumatter.

Before calling the API:
Use List Folders / フォルダ一覧取得 to check whether a folder with the same name already exists.
If the same folder name already exists, tell the user and ask whether to create another folder with the same name.
Do not call the Create Folder API for a duplicate unless the user explicitly confirms creating another folder.
Ask the user to confirm the folder name.

Endpoint:
POST https://agent-dev.bukumatter.com/api/edit/{handle}/folders

Headers:
X-Bukumatter-Agent-Key: <Agent Key>
X-Bukumatter-Agent-Manifest-Version: <Local manifest version>
Content-Type: application/json

Body:
{
  "name": "<folder name>",
  "description": ""
}

Rules:
- Use the Handle and Agent Key from this local file.
- Do not display the Agent Key in chat.
- Send Local manifest version as X-Bukumatter-Agent-Manifest-Version.
- Use List Folders / フォルダ一覧取得 before creating a folder to avoid accidental duplicates.
- Do not include isVisible in the request body.
- Created folders are private.
- AIエージェント連携版では、作成されるフォルダは非公開です。

### List Folders / フォルダ一覧取得

Status:
Available

What the agent can do:
List active folders for the authenticated agent user.

When to use:
Use this before adding a bookmark when the user specifies a folder name.

Endpoint:
GET https://agent-dev.bukumatter.com/api/edit/{handle}/folders

Headers:
X-Bukumatter-Agent-Key: <Agent Key>
X-Bukumatter-Agent-Manifest-Version: <Local manifest version>

Rules:
- Use the Handle and Agent Key from this local file.
- Do not display the Agent Key in chat.
- Send Local manifest version as X-Bukumatter-Agent-Manifest-Version.
- Use the returned folder id as folderId when adding a bookmark into a folder.
- Do not claim that folder visibility can be changed through the AI agent integration API.

### List Bookmarks / ブックマーク一覧取得

Status:
Available

What the agent can do:
List active bookmarks for the authenticated agent user.

When to use:
Use this before adding a bookmark to check whether the same URL already exists.

Endpoint:
GET https://agent-dev.bukumatter.com/api/edit/{handle}/urls

Query:
folderId=<folder id> (optional)

Headers:
X-Bukumatter-Agent-Key: <Agent Key>
X-Bukumatter-Agent-Manifest-Version: <Local manifest version>

Rules:
- Use the Handle and Agent Key from this local file.
- Do not display the Agent Key in chat.
- Send Local manifest version as X-Bukumatter-Agent-Manifest-Version.
- Use folderId query when checking bookmarks in a specific folder.
- When checking bookmarks outside folders, call this endpoint without folderId and compare only bookmarks whose folderId is null.
- Compare normalized URLs when checking for duplicates.
- If the same URL already exists in the target location, tell the user and ask whether to add another copy.

### Add Bookmark / ブックマーク追加

Status:
Available

What the agent can do:
Add a private bookmark in Bukumatter.

Before calling the API:
Verify that the URL exists and is reachable when possible.
If the URL is not reachable, do not call the API unless the user explicitly confirms adding an unverified bookmark.
If the user does not provide a site name, do not call the API immediately.
Try to infer a site name from the page title first, then from the domain.
If the user specifies a folder name, use List Folders / フォルダ一覧取得 to find the matching folder before calling the API.
If exactly one matching folder is found, tell the user that folder will be used and ask for confirmation.
If multiple matching folders are found, ask the user to choose one.
If no matching folder is found, ask whether to add the bookmark outside a folder or create the folder first.
Before adding a bookmark, use List Bookmarks / ブックマーク一覧取得 to check whether the same URL already exists in the target location.
If adding into a folder, check bookmarks with that folderId.
If adding outside a folder, check bookmarks without folderId and compare only bookmarks whose folderId is null.
If the same URL already exists in the target location, tell the user and ask whether to add another copy.
Do not call the Add Bookmark API for a duplicate unless the user explicitly confirms adding another copy.
Tell the user which bookmark will be added, including its URL and site name.
Ask the user to confirm.

Endpoint:
POST https://agent-dev.bukumatter.com/api/edit/{handle}/urls

Headers:
X-Bukumatter-Agent-Key: <Agent Key>
X-Bukumatter-Agent-Manifest-Version: <Local manifest version>
Content-Type: application/json

Body:
{
  "url": "<URL>",
  "siteName": "<site name>",
  "folderId": null
}

Rules:
- Use the Handle and Agent Key from this local file.
- Do not display the Agent Key in chat.
- Send Local manifest version as X-Bukumatter-Agent-Manifest-Version.
- Use Add Bookmark / ブックマーク追加 as the feature name.
- Use only Add Bookmark / ブックマーク追加 for the feature name in user-facing status messages.
- Use folderId: null when adding a bookmark outside a folder.
- Use an existing folder id from List Folders / フォルダ一覧取得 when adding a bookmark into a folder.
- Use List Bookmarks / ブックマーク一覧取得 before adding a bookmark to avoid accidental duplicates.
- Do not include isVisible in the request body.
- Added bookmarks are private.
- AIエージェント連携版では、追加されるブックマークは非公開です。

### Move Bookmark / ブックマーク移動

Status:
Available

What the agent can do:
Move an existing bookmark into a folder or outside folders in Bukumatter.

Before calling the API:
Use List Bookmarks / ブックマーク一覧取得 to find the target bookmark.
Use List Folders / フォルダ一覧取得 to find the destination folder when moving into a folder.
If moving outside folders, use folderId: null.
If exactly one matching bookmark and destination are found, tell the user which bookmark will be moved and ask for confirmation.
If multiple matching bookmarks or folders are found, ask the user to choose one.
If no matching bookmark or destination folder is found, do not call the API.
Tell the user the current location and the new location.
Ask the user to confirm.

Endpoint:
PATCH https://agent-dev.bukumatter.com/api/edit/{handle}/urls/{urlId}/folder

Headers:
X-Bukumatter-Agent-Key: <Agent Key>
X-Bukumatter-Agent-Manifest-Version: <Local manifest version>
Content-Type: application/json

Body:
{
  "folderId": "<destination folder id or null>"
}

Rules:
- Use the Handle and Agent Key from this local file.
- Do not display the Agent Key in chat.
- Send Local manifest version as X-Bukumatter-Agent-Manifest-Version.
- Use Move Bookmark / ブックマーク移動 as the feature name.
- Use only Move Bookmark / ブックマーク移動 for the feature name in user-facing status messages.
- Only update folderId and the destination sort order.
- Use folderId: null when moving a bookmark outside folders.
- Use an existing folder id from List Folders / フォルダ一覧取得 when moving a bookmark into a folder.
- Do not change url, siteName, isVisible, or isArchived.
- Moved bookmarks remain private.

### Delete Bookmark / ブックマーク削除

Status:
Available

What the agent can do:
Delete an existing bookmark from Bukumatter.

Before calling the API:
Use List Bookmarks / ブックマーク一覧取得 to find the target bookmark.
If exactly one matching bookmark is found, tell the user which bookmark will be deleted and ask for confirmation.
If multiple matching bookmarks are found, ask the user to choose one.
If no matching bookmark is found, do not call the API.
Tell the user the bookmark URL, site name, and location.
Ask the user to confirm deletion.

Endpoint:
DELETE https://agent-dev.bukumatter.com/api/edit/{handle}/urls/{urlId}

Headers:
X-Bukumatter-Agent-Key: <Agent Key>
X-Bukumatter-Agent-Manifest-Version: <Local manifest version>

Rules:
- Use the Handle and Agent Key from this local file.
- Do not display the Agent Key in chat.
- Send Local manifest version as X-Bukumatter-Agent-Manifest-Version.
- Use Delete Bookmark / ブックマーク削除 as the feature name.
- Use only Delete Bookmark / ブックマーク削除 for the feature name in user-facing status messages.
- Deleted bookmarks will no longer appear in normal AI agent bookmark lists.
- Use deletion wording only.

### Delete Folder / フォルダ削除

Status:
Available

What the agent can do:
Delete an existing folder and the bookmarks inside it from Bukumatter.

Before calling the API:
Use List Folders / フォルダ一覧取得 to find the target folder.
Use List Bookmarks / ブックマーク一覧取得 with folderId to count bookmarks inside the folder.
Tell the user how many bookmarks will be deleted with the folder.
If practical, list the bookmarks that will be deleted.
If exactly one matching folder is found, tell the user which folder will be deleted and ask for confirmation.
If multiple matching folders are found, ask the user to choose one.
If no matching folder is found, do not call the API.
Ask the user to confirm deleting the folder and its bookmarks.

Endpoint:
DELETE https://agent-dev.bukumatter.com/api/edit/{handle}/folders/{folderId}

Headers:
X-Bukumatter-Agent-Key: <Agent Key>
X-Bukumatter-Agent-Manifest-Version: <Local manifest version>

Rules:
- Use the Handle and Agent Key from this local file.
- Do not display the Agent Key in chat.
- Send Local manifest version as X-Bukumatter-Agent-Manifest-Version.
- Use Delete Folder / フォルダ削除 as the feature name.
- Use only Delete Folder / フォルダ削除 for the feature name in user-facing status messages.
- Deleting a folder also deletes the bookmarks inside that folder.
- Deleted folders and bookmarks will no longer appear in normal AI agent lists.
- Use deletion wording only.

### Rename Bookmark / ブックマーク名変更

Status:
Available

What the agent can do:
Rename an existing bookmark in Bukumatter by updating its site name.

Before calling the API:
Use List Bookmarks / ブックマーク一覧取得 to find the target bookmark.
If exactly one matching bookmark is found, tell the user which bookmark will be renamed and ask for confirmation.
If multiple matching bookmarks are found, ask the user to choose one.
If no matching bookmark is found, do not call the API.
Tell the user the current site name and the new site name.
Ask the user to confirm.

Endpoint:
PATCH https://agent-dev.bukumatter.com/api/edit/{handle}/urls/{urlId}

Headers:
X-Bukumatter-Agent-Key: <Agent Key>
X-Bukumatter-Agent-Manifest-Version: <Local manifest version>
Content-Type: application/json

Body:
{
  "siteName": "<new site name>"
}

Rules:
- Use the Handle and Agent Key from this local file.
- Do not display the Agent Key in chat.
- Send Local manifest version as X-Bukumatter-Agent-Manifest-Version.
- Use Rename Bookmark / ブックマーク名変更 as the feature name.
- Use only Rename Bookmark / ブックマーク名変更 for the feature name in user-facing status messages.
- Only update siteName.
- Do not change url, folderId, isVisible, or isArchived.
- Renamed bookmarks remain private.

### Rename Folder / フォルダ名変更

Status:
Available

What the agent can do:
Rename an existing folder in Bukumatter by updating its folder name.

Before calling the API:
Use List Folders / フォルダ一覧取得 to find the target folder.
If exactly one matching folder is found, tell the user which folder will be renamed and ask for confirmation.
If multiple matching folders are found, ask the user to choose one.
If no matching folder is found, do not call the API.
Tell the user the current folder name and the new folder name.
Ask the user to confirm.

Endpoint:
PATCH https://agent-dev.bukumatter.com/api/edit/{handle}/folders/{folderId}

Headers:
X-Bukumatter-Agent-Key: <Agent Key>
X-Bukumatter-Agent-Manifest-Version: <Local manifest version>
Content-Type: application/json

Body:
{
  "name": "<new folder name>"
}

Rules:
- Use the Handle and Agent Key from this local file.
- Do not display the Agent Key in chat.
- Send Local manifest version as X-Bukumatter-Agent-Manifest-Version.
- Use Rename Folder / フォルダ名変更 as the feature name.
- Use only Rename Folder / フォルダ名変更 for the feature name in user-facing status messages.
- Only update name.
- Do not change description, parentFolder, isVisible, or isArchived.
- Renamed folders remain private.

After any Bukumatter API response:
- Check the manifest field in the response.
- If manifest.isClientOutdated is true, tell the user that the local Bukumatter agent manifest is outdated and offer to refresh this local file from manifest.latestManifestUrl.
- Do not display credentials in chat.

## Current Status / 現在の状態

- Registration is complete.
- Folder creation is available.
- Folder listing is available.
- List Bookmarks is available.
- Add Bookmark is available.
- Move Bookmark is available.
- Delete Bookmark is available.
- Delete Folder is available.
- Rename Bookmark is available.
- Rename Folder is available.
- 登録は完了しています。
- フォルダ作成は利用できます。
- フォルダ一覧取得を利用できます。
- ブックマーク一覧取得を利用できます。
- ブックマーク追加を利用できます。
- ブックマーク移動を利用できます。
- ブックマーク削除を利用できます。
- フォルダ削除を利用できます。
- ブックマーク名変更を利用できます。
- フォルダ名変更を利用できます。
```

Fill in the handle, password, and agent key in the local file.
Do not display those credential values in chat.

## Completion Message

After saving the local file, say:

```text
登録が完了しました。

ブクマッターのAIエージェント連携版で利用するユーザー、パスワード、エージェントキーを発行し、bukumatter-agent.local.md に保存しました。

このファイルには認証情報が含まれています。コミットしたり、公開したりしないでください。
```

Do not ask for a URL to bookmark after registration.