<!--
hoody-notes Subskill (cli)
Auto-generated by Hoody Skills Generator
Generated: 2026-06-19T23:18:14.333Z
Model: mimo-v2.5-pro
Mode: cli


Tokens: 21434

DO NOT EDIT MANUALLY - Changes will be overwritten on next generation
-->

# hoody-notes.md — Subskill Reference

## Overview

Hoody Notes is a collaborative knowledge management service providing notebooks, document nodes, rich-text editing, comments, versioning, databases, file attachments, and real-time collaboration. It serves as the primary structured content layer within Hoody Kit.

### When to Use This Service

- Creating and managing collaborative notebooks (top-level workspaces)
- Building hierarchical content structures with pages, folders, channels, databases
- Editing rich-text documents with block-level operations (append, patch, replace)
- Managing threaded comments anchored to specific document locations
- Tracking document history with version snapshots and restore
- Storing structured data in database nodes with typed fields
- Uploading and downloading file attachments via resumable TUS protocol
- Controlling access with per-node collaborator roles and notebook-level user management
- Recording user interactions (seen, opened) for activity tracking
- Adding emoji reactions to any node
- Batch-processing multiple mutations in a single request

### Service Philosophy Fit

Hoody Notes embodies the Hoody philosophy of containerized, user-owned data. Each notebook lives inside a Hoody container, providing:

- **Data isolation**: Notebook data is scoped to the container, never shared across tenants.
- **CLI-first operations**: Every API action maps to a `hoody notes` CLI command. No raw HTTP calls required.
- **Automatic provisioning**: The first call to `hoody notes whoami` auto-creates a user and default notebook.
- **Domain routing**: Access via `https://{projectId}-{containerId}-notes-{serviceId}.{node}.containers.hoody.com` with zero DNS configuration and automatic SSL.
- **Built-in authentication**: All requests are authenticated through the Hoody API token layer.

### Prerequisites

- A running Hoody container with the `notes` service
- Hoody CLI installed and authenticated (`hoody auth login` or `HOODY_TOKEN` env var)
- Container ID known (from `hoody containers list`)

---

## Common Workflows

### Workflow 1: Bootstrap — Identity and First Notebook

Every session starts by confirming your identity. The `/me` endpoint auto-provisions a user and default notebook on first access.

**Step 1: Verify authentication and get identity**

```
hoody notes whoami -c abc123 -o json
```

Response includes `userId`, `username`, `role`, and `notebookId`:

```
{
  "userId": "usr_64a1b2c3d4e5f6a7b8c9d0e1",
  "username": "alice",
  "role": "owner",
  "notebookId": "nb_9876543210abcdef"
}
```

**Step 2: List existing notebooks**

```
hoody notes list -c abc123 -o json
```

Returns all notebooks where the user has a role other than `"none"`:

```
[
  {
    "notebookId": "nb_9876543210abcdef",
    "name": "Alice Workspace",
    "description": "",
    "status": "active",
    "role": "owner",
    "avatarUrl": null
  }
]
```

**Step 3: Create an additional notebook**

```
hoody notes create --name "Project Alpha" --description "Engineering notes for Project Alpha" -c abc123 -o json
```

```
{
  "notebookId": "nb_abcdef1234567890",
  "name": "Project Alpha",
  "description": "Engineering notes for Project Alpha",
  "status": "active",
  "role": "owner",
  "avatarUrl": null
}
```

**Step 4: Verify creation**

```
hoody notes get --notebook-id nb_abcdef1234567890 -c abc123 -o json
```

```
{
  "notebookId": "nb_abcdef1234567890",
  "name": "Project Alpha",
  "description": "Engineering notes for Project Alpha",
  "status": "active",
  "role": "owner",
  "avatarUrl": null
}
```

---

### Workflow 2: Create a Page and Edit Its Document

Pages are nodes of type `"page"`. Documents are rich-text content attached to nodes.

**Step 1: Create a page node**

```
hoody notes create --notebook-id nb_abcdef1234567890 --type page --name "Architecture Overview" -c abc123 -o json
```

Required fields: `type` (string) and `attributes` (object). The `--name` flag maps to `attributes.name`.

```
{
  "nodeId": "node_fedcba9876543210",
  "type": "page",
  "notebookId": "nb_abcdef1234567890",
  "attributes": {
    "name": "Architecture Overview",
    "description": "",
    "alias": "architecture-overview"
  },
  "createdAt": "2025-11-05T10:30:00.000Z",
  "updatedAt": "2025-11-05T10:30:00.000Z"
}
```

**Step 2: Replace the document content (full overwrite)**

Use `put` to create or fully replace a document. Required field: `content` (object).

```
hoody notes put --notebook-id nb_abcdef1234567890 --node-id node_fedcba9876543210 --content '{"blocks":[{"type":"heading","attrs":{"level":1},"content":[{"type":"text","text":"System Architecture"}]}]}' -c abc123 -o json
```

```
{
  "nodeId": "node_fedcba9876543210",
  "version": 1
}
```

**Step 3: Append additional blocks to the document**

Use `append` to add blocks to the end of a document. Required fields: `blocks` (array), each block requires `content[].type` (string), `content[].text` (string).

```
hoody notes append --notebook-id nb_abcdef1234567890 --node-id node_fedcba9876543210 --blocks '[{"content":[{"type":"text","text":"This document describes the system architecture."}]}]' -c abc123 -o json
```

```
{
  "nodeId": "node_fedcba9876543210",
  "version": 2
}
```

**Step 4: Merge content with patch (preserves existing blocks)**

Use `patch` to merge top-level content. Required field: `content` (object).

```
hoody notes patch --notebook-id nb_abcdef1234567890 --node-id node_fedcba9876543210 --content '{"blocks":[{"type":"callout","attrs":{"type":"info"},"content":[{"type":"text","text":"Last reviewed: November 2025"}]}]}' -c abc123 -o json
```

```
{
  "nodeId": "node_fedcba9876543210",
  "version": 3
}
```

**Step 5: Retrieve the document**

```
hoody notes get --notebook-id nb_abcdef1234567890 --node-id node_fedcba9876543210 -c abc123 -o json
```

Returns the full document content with all blocks merged.

**Step 6: Resolve a node by its URL alias**

```
hoody notes get-by-alias --notebook-id nb_abcdef1234567890 --alias architecture-overview -c abc123 -o json
```

Returns the same node data as `get` by ID.

---

### Workflow 3: Hierarchical Content with Folders and Child Nodes

**Step 1: Create a folder node**

```
hoody notes create --notebook-id nb_abcdef1234567890 --type folder --name "Engineering" -c abc123 -o json
```

```
{
  "nodeId": "node_folder001engineering",
  "type": "folder",
  "notebookId": "nb_abcdef1234567890",
  "attributes": {
    "name": "Engineering",
    "description": ""
  },
  "createdAt": "2025-11-05T11:00:00.000Z",
  "updatedAt": "2025-11-05T11:00:00.000Z"
}
```

**Step 2: Create a child page inside the folder**

```
hoody notes create --notebook-id nb_abcdef1234567890 --type page --name "API Design" --parent-id node_folder001engineering -c abc123 -o json
```

```
{
  "nodeId": "node_apidesign001page",
  "type": "page",
  "notebookId": "nb_abcdef1234567890",
  "parentId": "node_folder001engineering",
  "attributes": {
    "name": "API Design",
    "description": ""
  },
  "createdAt": "2025-11-05T11:05:00.000Z",
  "updatedAt": "2025-11-05T11:05:00.000Z"
}
```

**Step 3: List children of the folder**

```
hoody notes children --notebook-id nb_abcdef1234567890 --node-id node_folder001engineering -c abc123 -o json
```

```
[
  {
    "nodeId": "node_apidesign001page",
    "type": "page",
    "parentId": "node_folder001engineering",
    "attributes": {
      "name": "API Design",
      "description": ""
    }
  }
]
```

**Step 4: List all nodes with optional filters**

```
hoody notes list --notebook-id nb_abcdef1234567890 --type page --limit 20 --offset 0 -c abc123 -o json
```

Returns a paginated list of page-type nodes. Supports filtering by `type`, `parentId`, and `rootId`.

**Step 5: Update a node's attributes**

```
hoody notes update --notebook-id nb_abcdef1234567890 --node-id node_apidesign001page --name "REST API Design" -c abc123 -o json
```

Required field: `attributes` (object). Type and parentId cannot be changed after creation.

```
{
  "nodeId": "node_apidesign001page",
  "type": "page",
  "attributes": {
    "name": "REST API Design",
    "description": ""
  }
}
```

**Step 6: Delete a node (permanent)**

```
hoody notes delete --notebook-id nb_abcdef1234567890 --node-id node_apidesign001page -c abc123 -o json
```

This permanently deletes the node and all associated data (documents, files, reactions, comments).

---

### Workflow 4: Comments and Collaboration

**Step 1: List comments on a node**

```
hoody notes list --notebook-id nb_abcdef1234567890 --node-id node_fedcba9876543210 --context comments -c abc123 -o json
```

Returns all comments with their content, author info, and anchor positions.

**Step 2: Create a comment**

```
hoody notes create --notebook-id nb_abcdef1234567890 --node-id node_fedcba9876543210 --context comments --content "This section needs more detail." -c abc123 -o json
```

```
{
  "commentId": "cmt_abc123def456",
  "nodeId": "node_fedcba9876543210",
  "content": "This section needs more detail.",
  "authorId": "usr_64a1b2c3d4e5f6a7b8c9d0e1",
  "createdAt": "2025-11-05T12:00:00.000Z",
  "resolved": false
}
```

**Step 3: List comment anchors (inline document positions)**

```
hoody notes anchors --notebook-id nb_abcdef1234567890 --node-id node_fedcba9876543210 -c abc123 -o json
```

Returns lightweight metadata for rendering inline comment decorations.

**Step 4: Edit a comment**

```
hoody notes edit --notebook-id nb_abcdef1234567890 --node-id node_fedcba9876543210 --comment-id cmt_abc123def456 --content "Updated: This section needs expanded detail with diagrams." -c abc123 -o json
```

**Step 5: Resolve a comment thread**

```
hoody notes resolve --notebook-id nb_abcdef1234567890 --node-id node_fedcba9876543210 --comment-id cmt_abc123def456 -c abc123 -o json
```

**Step 6: Delete a comment**

```
hoody notes delete --notebook-id nb_abcdef1234567890 --node-id node_fedcba9876543210 --comment-id cmt_abc123def456 --context comments -c abc123 -o json
```

---

### Workflow 5: Node Collaborators and Access Control

**Step 1: List collaborators on a node**

```
hoody notes list --notebook-id nb_abcdef1234567890 --node-id node_fedcba9876543210 --context collaborators -c abc123 -o json
```

```
[
  {
    "collaboratorId": "coll_owner001",
    "userId": "usr_64a1b2c3d4e5f6a7b8c9d0e1",
    "username": "alice",
    "role": "admin"
  }
]
```

**Step 2: Add a collaborator**

```
hoody notes add --notebook-id nb_abcdef1234567890 --node-id node_fedcba9876543210 --context collaborators --user-id usr_bob23456789abcdef --role collaborator -c abc123 -o json
```

```
{
  "collaboratorId": "coll_bob001",
  "userId": "usr_bob23456789abcdef",
  "username": "bob",
  "role": "collaborator"
}
```

**Step 3: Update a collaborator's role**

```
hoody notes update --notebook-id nb_abcdef1234567890 --node-id node_fedcba9876543210 --context collaborators --collaborator-id coll_bob001 --role admin -c abc123 -o json
```

**Step 4: Remove a collaborator**

```
hoody notes remove --notebook-id nb_abcdef1234567890 --node-id node_fedcba9876543210 --context collaborators --collaborator-id coll_bob001 -c abc123 -o json
```

---

### Workflow 6: Reactions and Interactions

**Step 1: Add an emoji reaction**

```
hoody notes add --notebook-id nb_abcdef1234567890 --node-id node_fedcba9876543210 --context reactions --emoji "👍" -c abc123 -o json
```

**Step 2: List reactions on a node**

```
hoody notes list --notebook-id nb_abcdef1234567890 --node-id node_fedcba9876543210 --context reactions -c abc123 -o json
```

```
[
  {
    "emoji": "👍",
    "userId": "usr_64a1b2c3d4e5f6a7b8c9d0e1",
    "username": "alice",
    "createdAt": "2025-11-05T12:30:00.000Z"
  }
]
```

**Step 3: Remove a reaction**

```
hoody notes remove --notebook-id nb_abcdef1234567890 --node-id node_fedcba9876543210 --context reactions --emoji "👍" -c abc123 -o json
```

**Step 4: Record that a node was seen**

```
hoody notes mark --notebook-id nb_abcdef1234567890 --node-id node_fedcba9876543210 --interaction seen -c abc123 -o json
```

Tracks first and last seen timestamps for the current user.

**Step 5: Record that a node was opened**

```
hoody notes mark --notebook-id nb_abcdef1234567890 --node-id node_fedcba9876543210 --interaction opened -c abc123 -o json
```

Tracks first and last opened timestamps for the current user.

---

### Workflow 7: Document Versioning

**Step 1: Capture a version snapshot**

```
hoody notes create --notebook-id nb_abcdef1234567890 --node-id node_fedcba9876543210 --context versions -c abc123 -o json
```

```
{
  "versionId": "ver_001",
  "nodeId": "node_fedcba9876543210",
  "revision": 1,
  "createdAt": "2025-11-05T13:00:00.000Z",
  "authorId": "usr_64a1b2c3d4e5f6a7b8c9d0e1"
}
```

**Step 2: List all versions**

```
hoody notes list --notebook-id nb_abcdef1234567890 --node-id node_fedcba9876543210 --context versions -c abc123 -o json
```

Returns versions ordered by revision descending (newest first).

**Step 3: Retrieve a specific version's content**

```
hoody notes get --notebook-id nb_abcdef1234567890 --node-id node_fedcba9876543210 --context versions --version-id ver_001 -c abc123 -o json
```

**Step 4: Restore to a previous version**

```
hoody notes restore --notebook-id nb_abcdef1234567890 --node-id node_fedcba9876543210 --version-id ver_001 -c abc123 -o json
```

Replaces the current document content with the version snapshot.

**Step 5: Delete a version**

```
hoody notes delete --notebook-id nb_abcdef1234567890 --node-id node_fedcba9876543210 --context versions --version-id ver_001 -c abc123 -o json
```

---

### Workflow 8: Database Nodes and Records

Database nodes are created as `type: "database"` and contain structured records with typed fields.

**Step 1: Create a database node**

```
hoody notes create --notebook-id nb_abcdef1234567890 --type database --name "Task Tracker" -c abc123 -o json
```

```
{
  "nodeId": "node_database001tasks",
  "type": "database",
  "notebookId": "nb_abcdef1234567890",
  "attributes": {
    "name": "Task Tracker",
    "description": ""
  }
}
```

**Step 2: Create a record in the database**

```
hoody notes create --notebook-id nb_abcdef1234567890 --database-id node_database001tasks --context records --name "Implement auth module" --fields '{"status":"in-progress","priority":"high","assignee":"alice"}' -c abc123 -o json
```

```
{
  "recordId": "rec_abc123",
  "databaseId": "node_database001tasks",
  "name": "Implement auth module",
  "fields": {
    "status": "in-progress",
    "priority": "high",
    "assignee": "alice"
  },
  "createdAt": "2025-11-05T14:00:00.000Z"
}
```

**Step 3: List records in a database**

```
hoody notes list --notebook-id nb_abcdef1234567890 --database-id node_database001tasks --context records --limit 50 --offset 0 -c abc123 -o json
```

Returns a paginated list. Supports JSON-encoded filters and sorts.

**Step 4: Search records by name**

```
hoody notes search --notebook-id nb_abcdef1234567890 --database-id node_database001tasks --query "auth" -c abc123 -o json
```

Supports excluding specific record IDs from results.

**Step 5: Get a specific record**

```
hoody notes get --notebook-id nb_abcdef1234567890 --database-id node_database001tasks --context records --record-id rec_abc123 -c abc123 -o json
```

**Step 6: Update a record (fields are merged)**

```
hoody notes update --notebook-id nb_abcdef1234567890 --database-id node_database001tasks --context records --record-id rec_abc123 --fields '{"status":"completed"}' -c abc123 -o json
```

```
{
  "recordId": "rec_abc123",
  "databaseId": "node_database001tasks",
  "name": "Implement auth module",
  "fields": {
    "status": "completed",
    "priority": "high",
    "assignee": "alice"
  }
}
```

**Step 7: Delete a record**

```
hoody notes delete --notebook-id nb_abcdef1234567890 --database-id node_database001tasks --context records --record-id rec_abc123 -c abc123 -o json
```

---

### Workflow 9: File Upload and Download (TUS Protocol)

Files use the TUS resumable upload protocol for reliable large file transfers.

**Step 1: List files in a notebook**

```
hoody notes list --notebook-id nb_abcdef1234567890 --context files -c abc123 -o json
```

```
[
  {
    "fileId": "file_abc123",
    "notebookId": "nb_abcdef1234567890",
    "name": "diagram.png",
    "contentType": "image/png",
    "size": 204800,
    "createdAt": "2025-11-05T15:00:00.000Z"
  }
]
```

**Step 2: Initiate a TUS upload**

```
hoody notes tus-init --notebook-id nb_abcdef1234567890 --file-id file_abc123 --size 204800 -c abc123 -o json
```

Creates the upload session on the server.

**Step 3: Upload file chunks**

```
hoody notes tus-upload --notebook-id nb_abcdef1234567890 --file-id file_abc123 --offset 0 --data @diagram.png -c abc123
```

For large files, send multiple chunks with incrementing offsets.

**Step 4: Check upload status**

```
hoody notes tus-check --notebook-id nb_abcdef1234567890 --file-id file_abc123 -c abc123
```

Returns current upload offset to resume from the correct position.

**Step 5: Download a file**

```
hoody notes download --notebook-id nb_abcdef1234567890 --file-id file_abc123 -c abc123
```

Returns the binary file data with the original content type.

**Step 6: Abort an in-progress upload**

```
hoody notes tus-abort --notebook-id nb_abcdef1234567890 --file-id file_abc123 -c abc123
```

---

### Workflow 10: Avatars

**Step 1: Upload an avatar**

```
hoody notes upload-avatar --file photo.jpg -c abc123 -o json
```

Accepts JPEG, PNG, or WebP. The image is resized to 500x500 and converted to JPEG.

```
{
  "avatarId": "av_abc123def456"
}
```

**Step 2: Download an avatar**

```
hoody notes download-avatar --avatar-id av_abc123def456 -c abc123
```

Returns JPEG binary data.

---

### Workflow 11: User Management in Notebooks

**Step 1: Add users to a notebook**

```
hoody notes create --notebook-id nb_abcdef1234567890 --context users --usernames "bob,charlie" -c abc123 -o json
```

```
{
  "created": [
    {
      "userId": "usr_bob23456789abcdef",
      "username": "bob",
      "role": "collaborator"
    },
    {
      "userId": "usr_charlie3456789abcdef",
      "username": "charlie",
      "role": "collaborator"
    }
  ],
  "errors": []
}
```

**Step 2: Change a user's notebook role**

```
hoody notes set-role --notebook-id nb_abcdef1234567890 --user-id usr_bob23456789abcdef --role admin -c abc123 -o json
```

Valid roles: `owner`, `admin`, `collaborator`, `guest`, `none`. Requires owner or admin permission.

---

## Advanced Operations

### Advanced Workflow 1: Document Export with Ticket

Exporting a node as static HTML requires a short-lived ticket.

**Step 1: Create an export ticket**

```
hoody notes export --notebook-id nb_abcdef1234567890 --node-id node_fedcba9876543210 -c abc123 -o json
```

```
{
  "ticket": "tkt_abc123def456ghi789",
  "expiresAt": "2025-11-05T14:00:00.000Z"
}
```

**Step 2: Use the ticket to fetch HTML output**

The ticket is required as a query parameter when fetching `output=html` from the document endpoint. The ticket is short-lived and single-use.

---

### Advanced Workflow 2: Batch Mutations

For bulk operations, use the mutations endpoint to send multiple actions in a single request.

**Step 1: Execute a batch of mutations**

```
hoody notes mutate --notebook-id nb_abcdef1234567890 --mutations '[{"action":"createNode","type":"page","attributes":{"name":"Page 1"}},{"action":"createNode","type":"page","attributes":{"name":"Page 2"}},{"action":"addReaction","nodeId":"node_fedcba9876543210","emoji":"🎉"}]' -c abc123 -o json
```

Returns per-mutation status results:

```
{
  "results": [
    {
      "status": "success",
      "index": 0,
      "data": {
        "nodeId": "node_batch001page1"
      }
    },
    {
      "status": "success",
      "index": 1,
      "data": {
        "nodeId": "node_batch002page2"
      }
    },
    {
      "status": "success",
      "index": 2,
      "data": {
        "emoji": "🎉"
      }
    }
  ]
}
```

Batch mutations support: node CRUD, reactions, interactions, and document operations.

---

### Advanced Workflow 3: Real-Time Collaboration via WebSockets

**Step 1: Initialize a socket session**

```
hoody notes socket-init -c abc123 -o json
```

```
{
  "socketId": "sock_abc123def456"
}
```

**Step 2: Open a WebSocket connection**

```
hoody notes socket-open --socket-id sock_abc123def456 -c abc123
```

Upgrades the HTTP connection to WebSocket for real-time document collaboration.

---

### Advanced Workflow 4: Drawing Blocks as SVG

**Step 1: Render a drawing block as SVG**

```
hoody notes render-svg --notebook-id nb_abcdef1234567890 --node-id node_fedcba9876543210 --block-id blk_drawing001 --scale 2 --background "#ffffff" -c abc123
```

Returns SVG image data. Useful for exporting whiteboard or drawing content.

---

### Advanced Workflow 5: Notebook Lifecycle Management

**Step 1: Update notebook settings**

```
hoody notes update --notebook-id nb_abcdef1234567890 --name "Project Alpha (Active)" --description "Updated description for active project" -c abc123 -o json
```

Required field: `name` (string).

```
{
  "notebookId": "nb_abcdef1234567890",
  "name": "Project Alpha (Active)",
  "description": "Updated description for active project",
  "status": "active"
}
```

**Step 2: Update notebook avatar**

```
hoody notes update --notebook-id nb_abcdef1234567890 --avatar-id av_abc123def456 -c abc123 -o json
```

**Step 3: Delete a notebook (irreversible)**

```
hoody notes delete --notebook-id nb_abcdef1234567890 -c abc123
```

Permanently deletes the notebook and ALL its data: nodes, documents, comments, versions, files, and records. Only notebook owners can delete.

---

### Error Recovery Patterns

**Pattern 1: Resumable file upload after interruption**

```
# Check current upload progress
hoody notes tus-check --notebook-id nb_abcdef1234567890 --file-id file_abc123 -c abc123

# Resume from the offset returned
hoody notes tus-upload --notebook-id nb_abcdef1234567890 --file-id file_abc123 --offset 102400 --data @diagram.png -c abc123
```

**Pattern 2: Version-based recovery after bad edits**

```
# List versions to find the last good state
hoody notes list --notebook-id nb_abcdef1234567890 --node-id node_fedcba9876543210 --context versions -c abc123 -o json

# Restore to the good version
hoody notes restore --notebook-id nb_abcdef1234567890 --node-id node_fedcba9876543210 --version-id ver_001 -c abc123 -o json
```

**Pattern 3: Verify notebook access before operations**

```
# Check your role on the notebook
hoody notes get --notebook-id nb_abcdef1234567890 -c abc123 -o json

# If role is "none", request access from an owner/admin
```

**Pattern 4: Health check for service availability**

```
hoody notes health -c abc123 -o json
```

```
{
  "status": "ok",
  "service": "notes",
  "version": "1.0.0",
  "startedAt": "2025-11-05T00:00:00.000Z",
  "pid": 1234,
  "memory": {
    "rss": 52428800,
    "heapUsed": 20971520
  }
}
```

---

### Performance Considerations

1. **Pagination**: All list endpoints support `limit` and `offset`. Use reasonable page sizes (20-50) to avoid large payloads. Default limits apply when not specified.

2. **Batch mutations**: When creating or updating multiple items, prefer the mutations endpoint over individual requests. This reduces round-trips and ensures atomicity per mutation.

3. **TUS resumable uploads**: For files larger than 5MB, always use the TUS protocol rather than attempting single-request uploads. Check upload progress with `tus-check` before resuming.

4. **Document operations**: Use `patch` instead of `put` when modifying a portion of a document. `put` replaces the entire document and is more expensive for large documents.

5. **Search vs. list**: Use the records search endpoint for name-based lookups. Use list with filters for structured queries. Avoid fetching all records without pagination.

6. **Version snapshots**: Create versions before major edits. Do not create versions on every keystroke — versions are meant for significant checkpoints.

---

## Quick Reference

### Health and Identity

| Command | Description |
|---------|-------------|
| `hoody notes health -c <id>` | Service health check with resource stats |
| `hoody notes whoami -c <id>` | Current user identity and default notebook |

### Notebooks

| Command | Description |
|---------|-------------|
| `hoody notes list -c <id>` | List all notebooks for current user |
| `hoody notes create --name "X" -c <id>` | Create a new notebook |
| `hoody notes get --notebook-id <id> -c <id>` | Get notebook metadata |
| `hoody notes update --notebook-id <id> --name "X" -c <id>` | Update notebook settings |
| `hoody notes delete --notebook-id <id> -c <id>` | Delete notebook permanently |

### Nodes

| Command | Description |
|---------|-------------|
| `hoody notes list --notebook-id <id> -c <id>` | List nodes (pages, folders, databases) |
| `hoody notes create --notebook-id <id> --type <type> --name "X" -c <id>` | Create node (type: page/folder/database/channel/message/record) |
| `hoody notes get --notebook-id <id> --node-id <id> -c <id>` | Get node details |
| `hoody notes get-by-alias --notebook-id <id> --alias <slug> -c <id>` | Resolve node by URL alias |
| `hoody notes update --notebook-id <id> --node-id <id> --name "X" -c <id>` | Update node attributes |
| `hoody notes delete --notebook-id <id> --node-id <id> -c <id>` | Delete node and descendants |
| `hoody notes children --notebook-id <id> --node-id <id> -c <id>` | List child nodes |

### Documents

| Command | Description |
|---------|-------------|
| `hoody notes get --notebook-id <id> --node-id <id> --context document -c <id>` | Get document content |
| `hoody notes put --notebook-id <id> --node-id <id> --content <json> -c <id>` | Replace entire document |
| `hoody notes patch --notebook-id <id> --node-id <id> --content <json> -c <id>` | Merge into document |
| `hoody notes append --notebook-id <id> --node-id <id> --blocks <json> -c <id>` | Append blocks to end |
| `hoody notes export --notebook-id <id> --node-id <id> -c <id>` | Create HTML export ticket |
| `hoody notes render-svg --notebook-id <id> --node-id <id> --block-id <id> -c <id>` | Render drawing block as SVG |

### Comments

| Command | Description |
|---------|-------------|
| `hoody notes list --notebook-id <id> --node-id <id> --context comments -c <id>` | List comments |
| `hoody notes create --notebook-id <id> --node-id <id> --context comments --content "X" -c <id>` | Create comment |
| `hoody notes anchors --notebook-id <id> --node-id <id> -c <id>` | List comment anchors |
| `hoody notes edit --notebook-id <id> --node-id <id> --comment-id <id> --content "X" -c <id>` | Edit comment |
| `hoody notes delete --notebook-id <id> --node-id <id> --comment-id <id> --context comments -c <id>` | Delete comment |
| `hoody notes resolve --notebook-id <id> --node-id <id> --comment-id <id> -c <id>` | Resolve comment thread |

### Versions

| Command | Description |
|---------|-------------|
| `hoody notes list --notebook-id <id> --node-id <id> --context versions -c <id>` | List version snapshots |
| `hoody notes create --notebook-id <id> --node-id <id> --context versions -c <id>` | Create version snapshot |
| `hoody notes get --notebook-id <id> --node-id <id> --context versions --version-id <id> -c <id>` | Get version content |
| `hoody notes delete --notebook-id <id> --node-id <id> --context versions --version-id <id> -c <id>` | Delete version |
| `hoody notes restore --notebook-id <id> --node-id <id> --version-id <id> -c <id>` | Restore to version |

### Database Records

| Command | Description |
|---------|-------------|
| `hoody notes list --notebook-id <id> --database-id <id> --context records -c <id>` | List records |
| `hoody notes create --notebook-id <id> --database-id <id> --context records --name "X" -c <id>` | Create record |
| `hoody notes search --notebook-id <id> --database-id <id> --query "X" -c <id>` | Search records by name |
| `hoody notes get --notebook-id <id> --database-id <id> --context records --record-id <id> -c <id>` | Get record |
| `hoody notes update --notebook-id <id> --database-id <id> --context records --record-id <id> --fields <json> -c <id>` | Update record fields |
| `hoody notes delete --notebook-id <id> --database-id <id> --context records --record-id <id> -c <id>` | Delete record |

### Collaborators

| Command | Description |
|---------|-------------|
| `hoody notes list --notebook-id <id> --node-id <id> --context collaborators -c <id>` | List collaborators |
| `hoody notes add --notebook-id <id> --node-id <id> --context collaborators --user-id <id> --role <role> -c <id>` | Add collaborator |
| `hoody notes update --notebook-id <id> --node-id <id> --context collaborators --collaborator-id <id> --role <role> -c <id>` | Update collaborator role |
| `hoody notes remove --notebook-id <id> --node-id <id> --context collaborators --collaborator-id <id> -c <id>` | Remove collaborator |

### Reactions and Interactions

| Command | Description |
|---------|-------------|
| `hoody notes list --notebook-id <id> --node-id <id> --context reactions -c <id>` | List reactions |
| `hoody notes add --notebook-id <id> --node-id <id> --context reactions --emoji "X" -c <id>` | Add reaction |
| `hoody notes remove --notebook-id <id> --node-id <id> --context reactions --emoji "X" -c <id>` | Remove reaction |
| `hoody notes mark --notebook-id <id> --node-id <id> --interaction seen -c <id>` | Mark as seen |
| `hoody notes mark --notebook-id <id> --node-id <id> --interaction opened -c <id>` | Mark as opened |

### Files and Avatars

| Command | Description |
|---------|-------------|
| `hoody notes list --notebook-id <id> --context files -c <id>` | List files |
| `hoody notes download --notebook-id <id> --file-id <id> -c <id>` | Download file |
| `hoody notes tus-init --notebook-id <id> --file-id <id> --size <bytes> -c <id>` | Initiate TUS upload |
| `hoody notes tus-upload --notebook-id <id> --file-id <id> --offset <n> -c <id>` | Upload TUS chunk |
| `hoody notes tus-check --notebook-id <id> --file-id <id> -c <id>` | Check TUS upload progress |
| `hoody notes tus-abort --notebook-id <id> --file-id <id> -c <id>` | Abort TUS upload |
| `hoody notes upload-avatar --file <path> -c <id>` | Upload avatar image |
| `hoody notes download-avatar --avatar-id <id> -c <id>` | Download avatar |

### Users and Batch

| Command | Description |
|---------|-------------|
| `hoody notes create --notebook-id <id> --context users --usernames "a,b" -c <id>` | Add users to notebook |
| `hoody notes set-role --notebook-id <id> --user-id <id> --role <role> -c <id>` | Change user notebook role |
| `hoody notes mutate --notebook-id <id> --mutations <json> -c <id>` | Execute batch mutations |

### Common Flags

| Flag | Description |
|------|-------------|
| `-c <container-id>` | Target container (required for all commands) |
| `-o json` | Machine-readable JSON output |
| `--token <token>` | API authentication token |
| `--notebook-id <id>` | Notebook context |
| `--node-id <id>` | Node context |
| `--database-id <id>` | Database context |
| `--limit <n>` | Pagination page size |
| `--offset <n>` | Pagination offset |

### Typical Response Formats

**Single resource** — returns the full resource object:

```
{
  "nodeId": "node_abc123",
  "type": "page",
  "attributes": {
    "name": "My Page"
  }
}
```

**Collection** — returns an array:

```
[
  {
    "nodeId": "node_abc123",
    "type": "page"
  },
  {
    "nodeId": "node_def456",
    "type": "folder"
  }
]
```

**Deletion** — returns `null` or empty body with 204 status.

**Health** — returns service identity, build info, resource counters, and process ID.

---

## Endpoint-to-CLI Mapping Reference

For agents that need to map API endpoints to CLI commands:

| API Endpoint | CLI Command |
|-------------|-------------|
| `GET /api/v1/notes/health` | `hoody notes health` |
| `GET /api/v1/notes/me` | `hoody notes whoami` |
| `POST /api/v1/notes/sockets` | `hoody notes socket-init` |
| `GET /api/v1/notes/sockets/{socketId}` | `hoody notes socket-open --socket-id <id>` |
| `POST /api/v1/notes/avatars` | `hoody notes upload-avatar --file <path>` |
| `GET /api/v1/notes/avatars/{avatarId}` | `hoody notes download-avatar --avatar-id <id>` |
| `GET /api/v1/notes/notebooks` | `hoody notes list` |
| `POST /api/v1/notes/notebooks` | `hoody notes create --name <name>` |
| `GET /api/v1/notes/notebooks/{id}` | `hoody notes get --notebook-id <id>` |
| `PATCH /api/v1/notes/notebooks/{id}` | `hoody notes update --notebook-id <id>` |
| `DELETE /api/v1/notes/notebooks/{id}` | `hoody notes delete --notebook-id <id>` |
| `GET /api/v1/notes/notebooks/{id}/nodes` | `hoody notes list --notebook-id <id>` |
| `POST /api/v1/notes/notebooks/{id}/nodes` | `hoody notes create --notebook-id <id>` |
| `GET /api/v1/notes/notebooks/{id}/nodes/alias/{alias}` | `hoody notes get-by-alias --notebook-id <id> --alias <alias>` |
| `GET /api/v1/notes/notebooks/{id}/nodes/{id}` | `hoody notes get --notebook-id <id> --node-id <id>` |
| `PATCH /api/v1/notes/notebooks/{id}/nodes/{id}` | `hoody notes update --notebook-id <id> --node-id <id>` |
| `DELETE /api/v1/notes/notebooks/{id}/nodes/{id}` | `hoody notes delete --notebook-id <id> --node-id <id>` |
| `GET .../nodes/{id}/children` | `hoody notes children --notebook-id <id> --node-id <id>` |
| `GET .../nodes/{id}/document` | `hoody notes get --context document` |
| `PUT .../nodes/{id}/document` | `hoody notes put --notebook-id <id> --node-id <id>` |
| `PATCH .../nodes/{id}/document` | `hoody notes patch --notebook-id <id> --node-id <id>` |
| `POST .../nodes/{id}/document/append` | `hoody notes append --notebook-id <id> --node-id <id>` |
| `POST .../nodes/{id}/export-ticket` | `hoody notes export --notebook-id <id> --node-id <id>` |
| `GET .../nodes/{id}/blocks/{id}/svg` | `hoody notes render-svg` |
| `GET .../nodes/{id}/collaborators` | `hoody notes list --context collaborators` |
| `POST .../nodes/{id}/collaborators` | `hoody notes add --context collaborators` |
| `PATCH .../collaborators/{id}` | `hoody notes update --context collaborators` |
| `DELETE .../collaborators/{id}` | `hoody notes remove --context collaborators` |
| `GET .../nodes/{id}/comments` | `hoody notes list --context comments` |
| `POST .../nodes/{id}/comments` | `hoody notes create --context comments` |
| `GET .../nodes/{id}/comment-anchors` | `hoody notes anchors` |
| `PATCH .../comments/{id}` | `hoody notes edit` |
| `DELETE .../comments/{id}` | `hoody notes delete --context comments` |
| `POST .../comments/{id}/resolve` | `hoody notes resolve` |
| `GET .../nodes/{id}/reactions` | `hoody notes list --context reactions` |
| `POST .../nodes/{id}/reactions` | `hoody notes add --context reactions` |
| `DELETE .../reactions/{emoji}` | `hoody notes remove --context reactions` |
| `POST .../interactions/seen` | `hoody notes mark --interaction seen` |
| `POST .../interactions/opened` | `hoody notes mark --interaction opened` |
| `GET .../nodes/{id}/versions` | `hoody notes list --context versions` |
| `POST .../nodes/{id}/versions` | `hoody notes create --context versions` |
| `GET .../versions/{id}` | `hoody notes get --context versions` |
| `DELETE .../versions/{id}` | `hoody notes delete --context versions` |
| `POST .../versions/{id}/restore` | `hoody notes restore` |
| `GET .../databases/{id}/records` | `hoody notes list --context records` |
| `POST .../databases/{id}/records` | `hoody notes create --context records` |
| `GET .../records/search` | `hoody notes search` |
| `GET .../records/{id}` | `hoody notes get --context records` |
| `PATCH .../records/{id}` | `hoody notes update --context records` |
| `DELETE .../records/{id}` | `hoody notes delete --context records` |
| `GET .../notebooks/{id}/files` | `hoody notes list --context files` |
| `GET .../files/{id}` | `hoody notes download` |
| `POST .../files/{id}/tus` | `hoody notes tus-init` |
| `PATCH .../files/{id}/tus` | `hoody notes tus-upload` |
| `HEAD .../files/{id}/tus` | `hoody notes tus-check` |
| `DELETE .../files/{id}/tus` | `hoody notes tus-abort` |
| `POST .../notebooks/{id}/users` | `hoody notes create --context users` |
| `PATCH .../users/{id}/role` | `hoody notes set-role` |
| `POST .../notebooks/{id}/mutations` | `hoody notes mutate` |