@nasebanal/cli 0.1.0 → 0.3.0

package/specs/target.yaml

@@ -1,14 +1,8 @@
 openapi: 3.0.3
 info:
   title: NASEBANAL - Target API
-  description: >-
-    Target API for NASEBANAL. Provides hierarchical target management: users define goals and organize them in a tree
-    structure. Parent-child links are persisted via `targets.parent_target_id` (authoritative since migration 0017); a
-    legacy cell-based storage layer is kept in sync best-effort for backward compatibility. Targets can be shared with
-    other users (read/write, optionally including the subtree and linked Recorder data), and ownership of a personal
-    target subtree can be transferred to a recipient via an email-approved migration flow. Supports user authentication
-    via Auth0 JWT and Personal Access Tokens (PAT).
-  version: 1.4.1
+  description: "Target API for NASEBANAL. Provides hierarchical target management: users define goals and organize them in a tree structure. Parent-child links are persisted via `targets.parent_target_id` (authoritative since migration 0017); a legacy cell-based storage layer is kept in sync best-effort for backward compatibility. Targets can be shared with other users (read/write, optionally including the subtree and linked Recorder data), and ownership of a personal target subtree can be transferred to a recipient via an email-approved migration flow. Supports user authentication via Auth0 JWT and Personal Access Tokens (PAT)."
+  version: 1.5.0
   contact:
     name: NASEBANAL
     url: https://www.nasebanal.com
@@ -29,7 +23,7 @@ paths:
       description: Returns the health status of the API.
       security: []
       responses:
-        '200':
+        "200":
           description: API is healthy
           content:
             application/json:
@@ -41,7 +35,8 @@ paths:
                 properties:
                   success:
                     type: boolean
-                    enum: [true]
+                    enum:
+                      - true
                   data:
                     type: object
                     properties:
@@ -59,26 +54,21 @@ paths:
       summary: Get current user profile
       description: Returns the authenticated user's profile information (resolved from the Account API).
       responses:
-        '200':
+        "200":
           description: User profile
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/UserResponse'
-        '401':
-          $ref: '#/components/responses/Unauthorized'
+                $ref: "#/components/schemas/UserResponse"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
   /api/v1/targets:
     get:
       operationId: listTargets
       tags:
         - Targets
       summary: List targets
-      description: >-
-        Returns all targets belonging to the authenticated user in the active namespace (personal, or the active
-        organization), ordered by last updated. By default each target includes its storage cells so clients do not
-        need to issue a follow-up GET /targets/{id} per row. Pass `fields=summary` to omit `cells` and reduce payload
-        size for callers (e.g. a tree/chart view) that only need `progress` — fetch full detail on demand via
-        GET /targets/{id}.
+      description: Returns all targets belonging to the authenticated user in the active namespace (personal, or the active organization), ordered by last updated. By default each target includes its storage cells so clients do not need to issue a follow-up GET /targets/{id} per row. Pass `fields=summary` to omit `cells` and reduce payload size for callers (e.g. a tree/chart view) that only need `progress` — fetch full detail on demand via GET /targets/{id}.
       parameters:
         - name: fields
           in: query
@@ -89,11 +79,9 @@ paths:
               - full
               - summary
             default: full
-          description: >-
-            `full` (default) returns every target's complete `cells` array — today's exact behavior, unchanged for
-            callers that omit this param. `summary` omits `cells`; `progress` is present in both modes.
+          description: "`full` (default) returns every target's complete `cells` array — today's exact behavior, unchanged for callers that omit this param. `summary` omits `cells`; `progress` is present in both modes."
       responses:
-        '200':
+        "200":
           description: List of targets with cells (or, with fields=summary, without cells)
           content:
             application/json:
@@ -105,7 +93,8 @@ paths:
                 properties:
                   success:
                     type: boolean
-                    enum: [true]
+                    enum:
+                      - true
                   data:
                     type: object
                     required:
@@ -115,7 +104,7 @@ paths:
                       data:
                         type: array
                         items:
-                          $ref: '#/components/schemas/TargetWithCells'
+                          $ref: "#/components/schemas/TargetWithCells"
                       total:
                         type: integer
               examples:
@@ -137,8 +126,8 @@ paths:
                           recorder_goal_id: null
                           progress: 40
                           own_progress: 40
-                          created_at: '2026-05-14T12:00:00Z'
-                          updated_at: '2026-05-14T12:00:00Z'
+                          created_at: 2026-05-14T12:00:00Z
+                          updated_at: 2026-05-14T12:00:00Z
                           owner_email: user@example.com
                           owner_name: Sample User
                           created_by_email: user@example.com
@@ -151,8 +140,8 @@ paths:
                               text: Learn Japanese
                               progress: 40
                               created_by_user_id: 42
-                              created_at: '2026-05-14T12:00:00Z'
-                              updated_at: '2026-05-14T12:00:00Z'
+                              created_at: 2026-05-14T12:00:00Z
+                              updated_at: 2026-05-14T12:00:00Z
                       total: 1
                 summary:
                   summary: fields=summary
@@ -172,67 +161,63 @@ paths:
                           recorder_goal_id: null
                           progress: 40
                           own_progress: 40
-                          created_at: '2026-05-14T12:00:00Z'
-                          updated_at: '2026-05-14T12:00:00Z'
+                          created_at: 2026-05-14T12:00:00Z
+                          updated_at: 2026-05-14T12:00:00Z
                           owner_email: user@example.com
                           owner_name: Sample User
                           created_by_email: user@example.com
                           created_by_name: Sample User
                           created_by_deleted: false
                       total: 1
-        '401':
-          $ref: '#/components/responses/Unauthorized'
+        "401":
+          $ref: "#/components/responses/Unauthorized"
     post:
       operationId: createTarget
       tags:
         - Targets
       summary: Create target
-      description: >-
-        Creates a new target. The storage cells are initialized with the target title pre-populated at position 40 (the
-        slot reserved for the target's own label). Optionally nests the new target under an existing parent.
+      description: Creates a new target. The storage cells are initialized with the target title pre-populated at position 40 (the slot reserved for the target's own label). Optionally nests the new target under an existing parent.
       requestBody:
         required: true
         content:
           application/json:
             schema:
-              $ref: '#/components/schemas/CreateTargetInput'
+              $ref: "#/components/schemas/CreateTargetInput"
       responses:
-        '201':
+        "201":
           description: Target created with its storage cells
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/TargetWithCellsResponse'
-        '400':
-          $ref: '#/components/responses/ValidationError'
-        '401':
-          $ref: '#/components/responses/Unauthorized'
-        '403':
-          $ref: '#/components/responses/Forbidden'
-        '404':
-          $ref: '#/components/responses/NotFound'
+                $ref: "#/components/schemas/TargetWithCellsResponse"
+        "400":
+          $ref: "#/components/responses/ValidationError"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
   /api/v1/targets/{id}:
     get:
       operationId: getTarget
       tags:
         - Targets
       summary: Get target
-      description: >-
-        Returns a single target with its storage cells. Accessible by the owner, by a user the target is shared with,
-        or by an admin of the organization that owns the target.
+      description: Returns a single target with its storage cells. Accessible by the owner, by a user the target is shared with, or by an admin of the organization that owns the target.
       parameters:
-        - $ref: '#/components/parameters/TargetId'
+        - $ref: "#/components/parameters/TargetId"
       responses:
-        '200':
+        "200":
           description: Target with cells
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/TargetWithCellsResponse'
-        '401':
-          $ref: '#/components/responses/Unauthorized'
-        '404':
-          $ref: '#/components/responses/NotFound'
+                $ref: "#/components/schemas/TargetWithCellsResponse"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          $ref: "#/components/responses/NotFound"
     put:
       operationId: updateTarget
       tags:
@@ -240,15 +225,15 @@ paths:
       summary: Update target
       description: Updates a target's title, description, memo, and/or its Recorder tag binding.
       parameters:
-        - $ref: '#/components/parameters/TargetId'
+        - $ref: "#/components/parameters/TargetId"
       requestBody:
         required: true
         content:
           application/json:
             schema:
-              $ref: '#/components/schemas/UpdateTargetInput'
+              $ref: "#/components/schemas/UpdateTargetInput"
       responses:
-        '200':
+        "200":
           description: Target updated
           content:
             application/json:
@@ -260,15 +245,16 @@ paths:
                 properties:
                   success:
                     type: boolean
-                    enum: [true]
+                    enum:
+                      - true
                   data:
-                    $ref: '#/components/schemas/Target'
-        '400':
-          $ref: '#/components/responses/ValidationError'
-        '401':
-          $ref: '#/components/responses/Unauthorized'
-        '404':
-          $ref: '#/components/responses/NotFound'
+                    $ref: "#/components/schemas/Target"
+        "400":
+          $ref: "#/components/responses/ValidationError"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          $ref: "#/components/responses/NotFound"
     delete:
       operationId: deleteTarget
       tags:
@@ -276,18 +262,18 @@ paths:
       summary: Delete target
       description: Deletes a target and all its cells.
       parameters:
-        - $ref: '#/components/parameters/TargetId'
+        - $ref: "#/components/parameters/TargetId"
       responses:
-        '200':
+        "200":
           description: Target deleted
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/SuccessFlagResponse'
-        '401':
-          $ref: '#/components/responses/Unauthorized'
-        '404':
-          $ref: '#/components/responses/NotFound'
+                $ref: "#/components/schemas/SuccessFlagResponse"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          $ref: "#/components/responses/NotFound"
   /api/v1/targets/{id}/cells/{position}:
     put:
       operationId: updateTargetCell
@@ -296,7 +282,7 @@ paths:
       summary: Update target cell
       description: Updates the text and/or progress of a specific storage cell on a target.
       parameters:
-        - $ref: '#/components/parameters/TargetId'
+        - $ref: "#/components/parameters/TargetId"
         - name: position
           in: path
           required: true
@@ -310,9 +296,9 @@ paths:
         content:
           application/json:
             schema:
-              $ref: '#/components/schemas/UpdateTargetCellInput'
+              $ref: "#/components/schemas/UpdateTargetCellInput"
       responses:
-        '200':
+        "200":
           description: Cell updated
           content:
             application/json:
@@ -324,35 +310,33 @@ paths:
                 properties:
                   success:
                     type: boolean
-                    enum: [true]
+                    enum:
+                      - true
                   data:
-                    $ref: '#/components/schemas/TargetCell'
-        '400':
-          $ref: '#/components/responses/ValidationError'
-        '401':
-          $ref: '#/components/responses/Unauthorized'
-        '404':
-          $ref: '#/components/responses/NotFound'
+                    $ref: "#/components/schemas/TargetCell"
+        "400":
+          $ref: "#/components/responses/ValidationError"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          $ref: "#/components/responses/NotFound"
   /api/v1/targets/{id}/parent:
     put:
       operationId: setTargetParent
       tags:
         - Targets
       summary: Set target parent
-      description: >-
-        Authoritative tree-move endpoint (migration 0017+). Sets or clears `parent_target_id` on the target. Pass
-        `null` to detach (move to root). The legacy sub-goal cells are updated best-effort to keep older clients in
-        sync. Parent and child must share the same organization namespace and the same owner; cycles are rejected.
+      description: Authoritative tree-move endpoint (migration 0017+). Sets or clears `parent_target_id` on the target. Pass `null` to detach (move to root). The legacy sub-goal cells are updated best-effort to keep older clients in sync. Parent and child must share the same organization namespace and the same owner; cycles are rejected.
       parameters:
-        - $ref: '#/components/parameters/TargetId'
+        - $ref: "#/components/parameters/TargetId"
       requestBody:
         required: true
         content:
           application/json:
             schema:
-              $ref: '#/components/schemas/SetTargetParentInput'
+              $ref: "#/components/schemas/SetTargetParentInput"
       responses:
-        '200':
+        "200":
           description: Parent updated; returns the updated target
           content:
             application/json:
@@ -364,33 +348,31 @@ paths:
                 properties:
                   success:
                     type: boolean
-                    enum: [true]
+                    enum:
+                      - true
                   data:
-                    $ref: '#/components/schemas/Target'
-        '400':
+                    $ref: "#/components/schemas/Target"
+        "400":
           description: Invalid move (self-parent, namespace mismatch, or cycle)
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/Error'
-        '401':
-          $ref: '#/components/responses/Unauthorized'
-        '403':
-          $ref: '#/components/responses/Forbidden'
-        '404':
-          $ref: '#/components/responses/NotFound'
+                $ref: "#/components/schemas/Error"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
   /api/v1/shared-targets:
     get:
       operationId: listSharedTargets
       tags:
         - Sharing
       summary: List targets shared with me
-      description: >-
-        Returns targets that other users have shared with the authenticated user and accepted (not paused, not hidden),
-        scoped to the active namespace via each share's `shared_with_org_id`. When `include_descendants` was set on the
-        share, the whole subtree is expanded. Each row carries the sharing owner and the effective permission.
+      description: Returns targets that other users have shared with the authenticated user and accepted (not paused, not hidden), scoped to the active namespace via each share's `shared_with_org_id`. When `include_descendants` was set on the share, the whole subtree is expanded. Each row carries the sharing owner and the effective permission.
       responses:
-        '200':
+        "200":
           description: Shared targets
           content:
             application/json:
@@ -402,7 +384,8 @@ paths:
                 properties:
                   success:
                     type: boolean
-                    enum: [true]
+                    enum:
+                      - true
                   data:
                     type: object
                     required:
@@ -412,48 +395,41 @@ paths:
                       data:
                         type: array
                         items:
-                          $ref: '#/components/schemas/SharedTarget'
+                          $ref: "#/components/schemas/SharedTarget"
                       total:
                         type: integer
-        '401':
-          $ref: '#/components/responses/Unauthorized'
+        "401":
+          $ref: "#/components/responses/Unauthorized"
   /api/v1/shares:
     get:
       operationId: listMyShares
       tags:
         - Sharing
       summary: List shares I created
-      description: >-
-        Returns shares the authenticated user owns (i.e. shares of their own targets), scoped to the active namespace.
-        Each row is enriched with the recipient email, the owner's plan, and the owner-side target chain.
+      description: Returns shares the authenticated user owns (i.e. shares of their own targets), scoped to the active namespace. Each row is enriched with the recipient email, the owner's plan, and the owner-side target chain.
       responses:
-        '200':
+        "200":
           description: Shares owned by the caller
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/ShareListResponse'
-        '401':
-          $ref: '#/components/responses/Unauthorized'
+                $ref: "#/components/schemas/ShareListResponse"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
     post:
       operationId: createShare
       tags:
         - Sharing
       summary: Create a share invitation
-      description: >-
-        Shares a target the caller owns with another user by email. Sends an invitation email containing an accept
-        link; the share is `pending` until accepted. Optionally includes the subtree (`include_descendants`) and the
-        linked Recorder tag data (`include_data`, which cascades matching tag shares to the Recorder API).
-        `share_context: organization` routes the share into the caller's active organization view and requires the
-        recipient to be a member of that organization.
+      description: "Shares a target the caller owns with another user by email. Sends an invitation email containing an accept link; the share is `pending` until accepted. Optionally includes the subtree (`include_descendants`) and the linked Recorder tag data (`include_data`, which cascades matching tag shares to the Recorder API). `share_context: organization` routes the share into the caller's active organization view and requires the recipient to be a member of that organization."
       requestBody:
         required: true
         content:
           application/json:
             schema:
-              $ref: '#/components/schemas/CreateShareInput'
+              $ref: "#/components/schemas/CreateShareInput"
       responses:
-        '201':
+        "201":
           description: Share created (pending acceptance)
           content:
             application/json:
@@ -465,64 +441,64 @@ paths:
                 properties:
                   success:
                     type: boolean
-                    enum: [true]
+                    enum:
+                      - true
                   data:
-                    $ref: '#/components/schemas/Share'
-        '400':
-          $ref: '#/components/responses/ValidationError'
-        '401':
-          $ref: '#/components/responses/Unauthorized'
-        '403':
+                    $ref: "#/components/schemas/Share"
+        "400":
+          $ref: "#/components/responses/ValidationError"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
           description: Sharing not permitted (plan limit, or recipient not in organization)
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/Error'
-        '404':
+                $ref: "#/components/schemas/Error"
+        "404":
           description: Target not found, or recipient email not registered
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/Error'
-        '409':
-          $ref: '#/components/responses/Conflict'
+                $ref: "#/components/schemas/Error"
+        "409":
+          $ref: "#/components/responses/Conflict"
   /api/v1/shares/with-me:
     get:
       operationId: listSharesWithMe
       tags:
         - Sharing
       summary: List shares addressed to me
-      description: >-
-        Returns shares where the authenticated user is the recipient, scoped to the active namespace. Filter by status
-        with the `status` query parameter. Each row is enriched with the owner email and the owner-side target chain.
+      description: Returns shares where the authenticated user is the recipient, scoped to the active namespace. Filter by status with the `status` query parameter. Each row is enriched with the owner email and the owner-side target chain.
       parameters:
         - name: status
           in: query
           required: false
           schema:
             type: string
-            enum: [accepted, pending, rejected, all]
+            enum:
+              - accepted
+              - pending
+              - rejected
+              - all
             default: accepted
           description: Which share statuses to return (default `accepted`).
       responses:
-        '200':
+        "200":
           description: Shares addressed to the caller
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/ShareListResponse'
-        '401':
-          $ref: '#/components/responses/Unauthorized'
+                $ref: "#/components/schemas/ShareListResponse"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
   /api/v1/shares/recipient-context-options:
     get:
       operationId: getRecipientContextOptions
       tags:
         - Sharing
       summary: Resolve sharing-context options for a recipient
-      description: >-
-        Returns which sharing contexts the caller may offer for a given recipient email. Always includes `personal`;
-        additionally includes `organization` when the caller is acting under an organization context and the recipient
-        is a member of that same organization.
+      description: Returns which sharing contexts the caller may offer for a given recipient email. Always includes `personal`; additionally includes `organization` when the caller is acting under an organization context and the recipient is a member of that same organization.
       parameters:
         - name: email
           in: query
@@ -532,7 +508,7 @@ paths:
             format: email
           description: Recipient email to evaluate.
       responses:
-        '200':
+        "200":
           description: Available sharing contexts
           content:
             application/json:
@@ -544,7 +520,8 @@ paths:
                 properties:
                   success:
                     type: boolean
-                    enum: [true]
+                    enum:
+                      - true
                   data:
                     type: object
                     required:
@@ -554,12 +531,16 @@ paths:
                         type: array
                         items:
                           type: string
-                          enum: [personal, organization]
-                        example: [personal, organization]
-        '400':
-          $ref: '#/components/responses/ValidationError'
-        '401':
-          $ref: '#/components/responses/Unauthorized'
+                          enum:
+                            - personal
+                            - organization
+                        example:
+                          - personal
+                          - organization
+        "400":
+          $ref: "#/components/responses/ValidationError"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
   /api/v1/shares/accept:
     post:
       operationId: acceptShareByToken
@@ -572,92 +553,88 @@ paths:
         content:
           application/json:
             schema:
-              $ref: '#/components/schemas/TokenInput'
+              $ref: "#/components/schemas/TokenInput"
       responses:
-        '200':
+        "200":
           description: Share accepted (or already accepted)
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/ShareStatusResponse'
-        '400':
+                $ref: "#/components/schemas/ShareStatusResponse"
+        "400":
           description: Invitation expired or already declined
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/Error'
-        '401':
-          $ref: '#/components/responses/Unauthorized'
-        '404':
-          $ref: '#/components/responses/NotFound'
+                $ref: "#/components/schemas/Error"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          $ref: "#/components/responses/NotFound"
   /api/v1/shares/migrate/accept:
     post:
       operationId: acceptMigrationByToken
       tags:
         - Sharing
       summary: Accept an ownership transfer by token
-      description: >-
-        Accepts a pending ownership-transfer (data migration) using the token from the migration approval email. On
-        success the target (and, if the share included descendants, its subtree) is transferred to the caller, and a
-        reverse read-only share is created so the original owner keeps access.
+      description: Accepts a pending ownership-transfer (data migration) using the token from the migration approval email. On success the target (and, if the share included descendants, its subtree) is transferred to the caller, and a reverse read-only share is created so the original owner keeps access.
       requestBody:
         required: true
         content:
           application/json:
             schema:
-              $ref: '#/components/schemas/TokenInput'
+              $ref: "#/components/schemas/TokenInput"
       responses:
-        '200':
+        "200":
           description: Ownership transferred
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/MigrationStatusResponse'
-        '400':
+                $ref: "#/components/schemas/MigrationStatusResponse"
+        "400":
           description: Migration invitation no longer active or expired
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/Error'
-        '401':
-          $ref: '#/components/responses/Unauthorized'
-        '404':
-          $ref: '#/components/responses/NotFound'
+                $ref: "#/components/schemas/Error"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          $ref: "#/components/responses/NotFound"
   /api/v1/shares/{id}:
     delete:
       operationId: deleteShare
       tags:
         - Sharing
       summary: Delete a share
-      description: >-
-        Removes a share the caller owns. If the share was created with `include_data`, the matching Recorder tag shares
-        are revoked unless `cascade_tag_shares=false` is passed. A share with a pending ownership transfer cannot be
-        deleted until the migration is cancelled.
+      description: Removes a share the caller owns. If the share was created with `include_data`, the matching Recorder tag shares are revoked unless `cascade_tag_shares=false` is passed. A share with a pending ownership transfer cannot be deleted until the migration is cancelled.
       parameters:
-        - $ref: '#/components/parameters/ShareId'
+        - $ref: "#/components/parameters/ShareId"
         - name: cascade_tag_shares
           in: query
           required: false
           schema:
             type: string
-            enum: ['true', 'false']
-            default: 'true'
+            enum:
+              - "true"
+              - "false"
+            default: "true"
           description: Set to `false` to keep the linked Recorder tag shares when deleting.
       responses:
-        '200':
+        "200":
           description: Share deleted
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/SuccessFlagResponse'
-        '400':
-          $ref: '#/components/responses/ValidationError'
-        '401':
-          $ref: '#/components/responses/Unauthorized'
-        '404':
-          $ref: '#/components/responses/NotFound'
-        '409':
-          $ref: '#/components/responses/Conflict'
+                $ref: "#/components/schemas/SuccessFlagResponse"
+        "400":
+          $ref: "#/components/responses/ValidationError"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "409":
+          $ref: "#/components/responses/Conflict"
   /api/v1/shares/{id}/accept:
     post:
       operationId: acceptShareById
@@ -666,24 +643,24 @@ paths:
       summary: Accept a share invitation (in-app)
       description: In-app counterpart to POST /shares/accept — accepts a pending share addressed to the caller by id.
       parameters:
-        - $ref: '#/components/parameters/ShareId'
+        - $ref: "#/components/parameters/ShareId"
       responses:
-        '200':
+        "200":
           description: Share accepted (or already accepted)
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/ShareStatusResponse'
-        '400':
+                $ref: "#/components/schemas/ShareStatusResponse"
+        "400":
           description: Invitation expired or already declined
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/Error'
-        '401':
-          $ref: '#/components/responses/Unauthorized'
-        '404':
-          $ref: '#/components/responses/NotFound'
+                $ref: "#/components/schemas/Error"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          $ref: "#/components/responses/NotFound"
   /api/v1/shares/{id}/reject:
     post:
       operationId: rejectShare
@@ -692,20 +669,20 @@ paths:
       summary: Reject a share invitation
       description: Declines a pending share addressed to the caller. An already-accepted share cannot be rejected (delete it instead).
       parameters:
-        - $ref: '#/components/parameters/ShareId'
+        - $ref: "#/components/parameters/ShareId"
       responses:
-        '200':
+        "200":
           description: Share rejected (or already rejected)
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/ShareStatusResponse'
-        '400':
-          $ref: '#/components/responses/ValidationError'
-        '401':
-          $ref: '#/components/responses/Unauthorized'
-        '404':
-          $ref: '#/components/responses/NotFound'
+                $ref: "#/components/schemas/ShareStatusResponse"
+        "400":
+          $ref: "#/components/responses/ValidationError"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          $ref: "#/components/responses/NotFound"
   /api/v1/shares/{id}/pause:
     patch:
       operationId: toggleSharePaused
@@ -714,7 +691,7 @@ paths:
       summary: Pause or resume a share
       description: Owner-only. Pauses or resumes a share without deleting it; a paused share is hidden from the recipient's shared-targets list.
       parameters:
-        - $ref: '#/components/parameters/ShareId'
+        - $ref: "#/components/parameters/ShareId"
       requestBody:
         required: true
         content:
@@ -727,7 +704,7 @@ paths:
                 is_paused:
                   type: boolean
       responses:
-        '200':
+        "200":
           description: Updated share row
           content:
             application/json:
@@ -739,13 +716,14 @@ paths:
                 properties:
                   success:
                     type: boolean
-                    enum: [true]
+                    enum:
+                      - true
                   data:
-                    $ref: '#/components/schemas/Share'
-        '401':
-          $ref: '#/components/responses/Unauthorized'
-        '404':
-          $ref: '#/components/responses/NotFound'
+                    $ref: "#/components/schemas/Share"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          $ref: "#/components/responses/NotFound"
   /api/v1/shares/{id}/visibility:
     patch:
       operationId: toggleShareVisibility
@@ -754,7 +732,7 @@ paths:
       summary: Hide or unhide a share
       description: Recipient-only. Hides or unhides a share from the caller's own shared-targets list.
       parameters:
-        - $ref: '#/components/parameters/ShareId'
+        - $ref: "#/components/parameters/ShareId"
       requestBody:
         required: true
         content:
@@ -767,7 +745,7 @@ paths:
                 is_hidden:
                   type: boolean
       responses:
-        '200':
+        "200":
           description: Updated share row
           content:
             application/json:
@@ -779,27 +757,25 @@ paths:
                 properties:
                   success:
                     type: boolean
-                    enum: [true]
+                    enum:
+                      - true
                   data:
-                    $ref: '#/components/schemas/Share'
-        '401':
-          $ref: '#/components/responses/Unauthorized'
-        '404':
-          $ref: '#/components/responses/NotFound'
+                    $ref: "#/components/schemas/Share"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          $ref: "#/components/responses/NotFound"
   /api/v1/shares/{id}/transfer:
     post:
       operationId: transferOwnership
       tags:
         - Sharing
       summary: Start an ownership transfer
-      description: >-
-        Owner-only. Begins transferring ownership of the shared target (subtree if the share included descendants) to
-        the recipient by emailing them an approval link. The share must already be accepted. Organization-owned targets
-        cannot be transferred. The transfer only completes when the recipient accepts.
+      description: Owner-only. Begins transferring ownership of the shared target (subtree if the share included descendants) to the recipient by emailing them an approval link. The share must already be accepted. Organization-owned targets cannot be transferred. The transfer only completes when the recipient accepts.
       parameters:
-        - $ref: '#/components/parameters/ShareId'
+        - $ref: "#/components/parameters/ShareId"
       responses:
-        '200':
+        "200":
           description: Migration invitation issued
           content:
             application/json:
@@ -811,7 +787,8 @@ paths:
                 properties:
                   success:
                     type: boolean
-                    enum: [true]
+                    enum:
+                      - true
                   data:
                     type: object
                     required:
@@ -822,20 +799,21 @@ paths:
                         type: integer
                       migration_status:
                         type: string
-                        enum: [pending]
+                        enum:
+                          - pending
                       expires_at:
                         type: string
                         format: date-time
-        '400':
-          $ref: '#/components/responses/ValidationError'
-        '401':
-          $ref: '#/components/responses/Unauthorized'
-        '403':
-          $ref: '#/components/responses/Forbidden'
-        '404':
-          $ref: '#/components/responses/NotFound'
-        '409':
-          $ref: '#/components/responses/Conflict'
+        "400":
+          $ref: "#/components/responses/ValidationError"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "409":
+          $ref: "#/components/responses/Conflict"
   /api/v1/shares/{id}/migrate/accept:
     post:
       operationId: acceptMigrationById
@@ -844,24 +822,24 @@ paths:
       summary: Accept an ownership transfer (in-app)
       description: In-app counterpart to POST /shares/migrate/accept — accepts a pending ownership transfer addressed to the caller by id.
       parameters:
-        - $ref: '#/components/parameters/ShareId'
+        - $ref: "#/components/parameters/ShareId"
       responses:
-        '200':
+        "200":
           description: Ownership transferred
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/MigrationStatusResponse'
-        '400':
+                $ref: "#/components/schemas/MigrationStatusResponse"
+        "400":
           description: Migration invitation no longer active or expired
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/Error'
-        '401':
-          $ref: '#/components/responses/Unauthorized'
-        '404':
-          $ref: '#/components/responses/NotFound'
+                $ref: "#/components/schemas/Error"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          $ref: "#/components/responses/NotFound"
   /api/v1/shares/{id}/migrate/reject:
     post:
       operationId: rejectMigration
@@ -870,20 +848,20 @@ paths:
       summary: Reject an ownership transfer
       description: Recipient-only. Declines a pending ownership transfer; the underlying share keeps its existing permission.
       parameters:
-        - $ref: '#/components/parameters/ShareId'
+        - $ref: "#/components/parameters/ShareId"
       responses:
-        '200':
+        "200":
           description: Migration rejected
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/MigrationStatusResponse'
-        '400':
-          $ref: '#/components/responses/ValidationError'
-        '401':
-          $ref: '#/components/responses/Unauthorized'
-        '404':
-          $ref: '#/components/responses/NotFound'
+                $ref: "#/components/schemas/MigrationStatusResponse"
+        "400":
+          $ref: "#/components/responses/ValidationError"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          $ref: "#/components/responses/NotFound"
   /api/v1/shares/{id}/migrate/cancel:
     post:
       operationId: cancelMigration
@@ -892,9 +870,9 @@ paths:
       summary: Cancel an ownership transfer
       description: Owner-only. Cancels an outstanding ownership-transfer invitation before the recipient acts.
       parameters:
-        - $ref: '#/components/parameters/ShareId'
+        - $ref: "#/components/parameters/ShareId"
       responses:
-        '200':
+        "200":
           description: Migration cancelled
           content:
             application/json:
@@ -906,7 +884,8 @@ paths:
                 properties:
                   success:
                     type: boolean
-                    enum: [true]
+                    enum:
+                      - true
                   data:
                     type: object
                     required:
@@ -918,14 +897,15 @@ paths:
                       migration_status:
                         type: string
                         nullable: true
-                        enum: [null]
+                        enum:
+                          - null
                         description: Always null after a cancel — the in-flight migration is cleared.
-        '400':
-          $ref: '#/components/responses/ValidationError'
-        '401':
-          $ref: '#/components/responses/Unauthorized'
-        '404':
-          $ref: '#/components/responses/NotFound'
+        "400":
+          $ref: "#/components/responses/ValidationError"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          $ref: "#/components/responses/NotFound"
 components:
   securitySchemes:
     BearerAuth:
@@ -1001,9 +981,10 @@ components:
       properties:
         success:
           type: boolean
-          enum: [true]
+          enum:
+            - true
         data:
-          $ref: '#/components/schemas/User'
+          $ref: "#/components/schemas/User"
     Target:
       type: object
       properties:
@@ -1020,14 +1001,11 @@ components:
         organization_id:
           type: integer
           nullable: true
-          description: >-
-            Organization namespace. NULL = personal data. Non-null = created under an Enterprise org context; the org
-            admin can read it and the member-creator owns it day-to-day but cannot transfer or delete it.
+          description: Organization namespace. NULL = personal data. Non-null = created under an Enterprise org context; the org admin can read it and the member-creator owns it day-to-day but cannot transfer or delete it.
         parent_target_id:
           type: string
           nullable: true
-          description: >-
-            Direct parent reference (migration 0017+). Authoritative source of tree structure. NULL = root target.
+          description: Direct parent reference (migration 0017+). Authoritative source of tree structure. NULL = root target.
         title:
           type: string
           description: Goal title
@@ -1041,14 +1019,15 @@ components:
         recorder_tag:
           type: string
           nullable: true
-          description: Optional tag linking to the Recorder app
+          description: Name of the linked Recorder tag, or a derived series key such as `Body Weight/BMI~` (a name, not a tag row, so it has no id). Kept alongside `recorder_tag_id` for derived keys and for clients that predate it.
+        recorder_tag_id:
+          type: integer
+          nullable: true
+          description: Id of the linked Recorder tag, for a real tag (never for a derived series key). Unlike the name it stays valid when the tag is renamed or its ownership is transferred, and it tells apart same-named tags of different owners. NULL for a target linked only by name; clients prefer the id when it is set and fall back to `recorder_tag`.
         recorder_goal_id:
           type: integer
           nullable: true
-          description: >-
-            Recorder Goal id pinned at the moment the tag was bound. Progress for this target is computed against this
-            specific goal so that later Goal period changes in Recorder do not silently re-route which goal is being
-            tracked.
+          description: Recorder Goal id pinned at the moment the tag was bound. Progress for this target is computed against this specific goal so that later Goal period changes in Recorder do not silently re-route which goal is being tracked.
         created_at:
           type: string
           format: date-time
@@ -1061,26 +1040,17 @@ components:
           description: Resolved owner email (present in response payloads).
         owner_name:
           type: string
-          description: >-
-            Display name the owner set in their profile. Absent when they set
-            none. Clients name the owner by this, falling back to a masked email.
+          description: Display name the owner set in their profile. Absent when they set none. Clients name the owner by this, falling back to a masked email.
         created_by_email:
           type: string
           format: email
-          description: >-
-            Resolved creator email (present in response payloads). Absent when `created_by_deleted` is true — there is no
-            creator left to name, and the owner must NOT be substituted.
+          description: Resolved creator email (present in response payloads). Absent when `created_by_deleted` is true — there is no creator left to name, and the owner must NOT be substituted.
         created_by_name:
           type: string
-          description: >-
-            Display name the creator set in their profile. Absent when they set
-            none, or when `created_by_deleted` is true.
+          description: Display name the creator set in their profile. Absent when they set none, or when `created_by_deleted` is true.
         created_by_deleted:
           type: boolean
-          description: >-
-            True when the author deleted their NASEBANAL account. The row itself survives because it belongs to this
-            target's owner; only the authorship is gone. Clients render a "deleted user" label (JA: 退会済ユーザー) rather
-            than falling back to `owner_email`, which would show the owner as the author of an edit they never made.
+          description: "True when the author deleted their NASEBANAL account. The row itself survives because it belongs to this target's owner; only the authorship is gone. Clients render a \"deleted user\" label (JA: 退会済ユーザー) rather than falling back to `owner_email`, which would show the owner as the author of an edit they never made."
     TargetCell:
       type: object
       properties:
@@ -1113,7 +1083,7 @@ components:
           format: date-time
     TargetWithCells:
       allOf:
-        - $ref: '#/components/schemas/Target'
+        - $ref: "#/components/schemas/Target"
         - type: object
           required:
             - progress
@@ -1122,30 +1092,18 @@ components:
             cells:
               type: array
               items:
-                $ref: '#/components/schemas/TargetCell'
-              description: >-
-                All storage cells ordered by position. Present when the list was requested without `fields`, or with
-                `fields=full` (the default); omitted when requested with `fields=summary` — see `progress` and
-                `own_progress` instead.
+                $ref: "#/components/schemas/TargetCell"
+              description: All storage cells ordered by position. Present when the list was requested without `fields`, or with `fields=full` (the default); omitted when requested with `fields=summary` — see `progress` and `own_progress` instead.
             progress:
               type: integer
               minimum: 0
               maximum: 100
-              description: >-
-                A target's own roll-up progress, computed server-side: the average of its children's (recursively
-                rolled-up) progress when it has sub-goals, or its own storage cell (position 40, `own_progress`)
-                when it's a leaf. Always present, regardless of `fields`.
+              description: "A target's own roll-up progress, computed server-side: the average of its children's (recursively rolled-up) progress when it has sub-goals, or its own storage cell (position 40, `own_progress`) when it's a leaf. Always present, regardless of `fields`."
             own_progress:
               type: integer
               minimum: 0
               maximum: 100
-              description: >-
-                The target's own storage cell (position 40) value, unrolled — what the "clear" toggle sets directly
-                to 0 or 100, independent of any sub-goals. Distinct from `progress`: a target with sub-goals can
-                have `progress = 100` (every child rolled up to 100) while `own_progress` stays whatever it was
-                last explicitly set to, since a parent's own cell is never averaged into its own `progress`. Always
-                present, regardless of `fields` — use this, not `progress`, to tell whether a target itself has
-                been marked cleared.
+              description: "The target's own storage cell (position 40) value, unrolled — what the \"clear\" toggle sets directly to 0 or 100, independent of any sub-goals. Distinct from `progress`: a target with sub-goals can have `progress = 100` (every child rolled up to 100) while `own_progress` stays whatever it was last explicitly set to, since a parent's own cell is never averaged into its own `progress`. Always present, regardless of `fields` — use this, not `progress`, to tell whether a target itself has been marked cleared."
     TargetWithCellsResponse:
       type: object
       required:
@@ -1154,12 +1112,13 @@ components:
       properties:
         success:
           type: boolean
-          enum: [true]
+          enum:
+            - true
         data:
-          $ref: '#/components/schemas/TargetWithCells'
+          $ref: "#/components/schemas/TargetWithCells"
     SharedTarget:
       allOf:
-        - $ref: '#/components/schemas/TargetWithCells'
+        - $ref: "#/components/schemas/TargetWithCells"
         - type: object
           properties:
             shared_by_user_id:
@@ -1173,13 +1132,17 @@ components:
               description: Display name the sharing owner set in their profile. Absent when they set none.
             share_permission:
               type: string
-              enum: [read, write]
+              enum:
+                - read
+                - write
             share_root_target_id:
               type: string
               description: The root target id of the share that grants access to this row
             share_show_embed:
               type: integer
-              enum: [0, 1]
+              enum:
+                - 0
+                - 1
               description: Whether the share permits embedding the linked Recorder graph
     Share:
       type: object
@@ -1194,17 +1157,24 @@ components:
           type: string
         permission:
           type: string
-          enum: [read, write]
+          enum:
+            - read
+            - write
         status:
           type: string
-          enum: [pending, accepted, rejected]
+          enum:
+            - pending
+            - accepted
+            - rejected
         expires_at:
           type: string
           format: date-time
           nullable: true
         migration_status:
           type: string
-          enum: [pending, null]
+          enum:
+            - pending
+            - null
           nullable: true
           description: Ownership-transfer state. NULL = no migration in flight.
         migration_expires_at:
@@ -1213,19 +1183,29 @@ components:
           nullable: true
         is_hidden:
           type: integer
-          enum: [0, 1]
+          enum:
+            - 0
+            - 1
         is_paused:
           type: integer
-          enum: [0, 1]
+          enum:
+            - 0
+            - 1
         show_embed:
           type: integer
-          enum: [0, 1]
+          enum:
+            - 0
+            - 1
         include_descendants:
           type: integer
-          enum: [0, 1]
+          enum:
+            - 0
+            - 1
         include_data:
           type: integer
-          enum: [0, 1]
+          enum:
+            - 0
+            - 1
         parent_share_id:
           type: integer
           nullable: true
@@ -1247,17 +1227,14 @@ components:
           description: Enriched — present when listing shares addressed to the caller.
         owner_name:
           type: string
-          description: >-
-            Display name the sharing owner set in their profile. Absent when they set none.
+          description: Display name the sharing owner set in their profile. Absent when they set none.
         shared_with_email:
           type: string
           format: email
           description: Enriched — present when listing shares the caller owns.
         shared_with_name:
           type: string
-          description: >-
-            Display name the recipient set in their profile. Set on shares the caller owns, and only once the share is
-            `accepted`, so an invitation does not reveal the profile of someone who has not accepted it.
+          description: Display name the recipient set in their profile. Set on shares the caller owns, and only once the share is `accepted`, so an invitation does not reveal the profile of someone who has not accepted it.
         owner_plan:
           type: string
           description: Enriched — the owner's plan, present when listing shares the caller owns.
@@ -1269,7 +1246,8 @@ components:
       properties:
         success:
           type: boolean
-          enum: [true]
+          enum:
+            - true
         data:
           type: object
           required:
@@ -1281,7 +1259,7 @@ components:
             data:
               type: array
               items:
-                $ref: '#/components/schemas/Share'
+                $ref: "#/components/schemas/Share"
             total:
               type: integer
             limit:
@@ -1296,7 +1274,8 @@ components:
       properties:
         success:
           type: boolean
-          enum: [true]
+          enum:
+            - true
         data:
           type: object
           required:
@@ -1307,7 +1286,10 @@ components:
               type: integer
             status:
               type: string
-              enum: [pending, accepted, rejected]
+              enum:
+                - pending
+                - accepted
+                - rejected
             already:
               type: boolean
               description: True when the share was already in the requested state.
@@ -1319,7 +1301,8 @@ components:
       properties:
         success:
           type: boolean
-          enum: [true]
+          enum:
+            - true
         data:
           type: object
           required:
@@ -1330,7 +1313,9 @@ components:
               type: integer
             migration_status:
               type: string
-              enum: [accepted, rejected]
+              enum:
+                - accepted
+                - rejected
     SuccessFlagResponse:
       type: object
       required:
@@ -1339,13 +1324,15 @@ components:
       properties:
         success:
           type: boolean
-          enum: [true]
+          enum:
+            - true
         data:
           type: object
           properties:
             success:
               type: boolean
-              enum: [true]
+              enum:
+                - true
     CreateTargetInput:
       type: object
       required:
@@ -1379,13 +1366,15 @@ components:
         recorder_tag:
           type: string
           nullable: true
-          description: Tag to link with Recorder app
+          description: Tag to link with Recorder app, by name. Send the name together with `recorder_tag_id` for a real tag; for a derived series key (`Body Weight/BMI~`) this is the only field.
+        recorder_tag_id:
+          type: integer
+          nullable: true
+          description: Id of the Recorder tag to link, for a real tag. Send it together with `recorder_tag`; send `null` for both to unlink.
         recorder_goal_id:
           type: integer
           nullable: true
-          description: >-
-            Pin a specific Recorder Goal to this target. Typically resolved by the client at bind time from the active
-            goal for the selected tag.
+          description: Pin a specific Recorder Goal to this target. Typically resolved by the client at bind time from the active goal for the selected tag.
     UpdateTargetCellInput:
       type: object
       properties:
@@ -1419,7 +1408,9 @@ components:
           type: string
         permission:
           type: string
-          enum: [read, write]
+          enum:
+            - read
+            - write
           default: read
         include_descendants:
           type: boolean
@@ -1431,11 +1422,11 @@ components:
           description: Also cascade-share the linked Recorder tag data so the recipient can view embedded graphs.
         share_context:
           type: string
-          enum: [personal, organization]
+          enum:
+            - personal
+            - organization
           default: personal
-          description: >-
-            `organization` routes the share into the caller's active organization view; requires the recipient to be a
-            member of that organization.
+          description: "`organization` routes the share into the caller's active organization view; requires the recipient to be a member of that organization."
         extra_tag_names:
           type: array
           items:
@@ -1457,7 +1448,8 @@ components:
       properties:
         success:
           type: boolean
-          enum: [false]
+          enum:
+            - false
         error:
           type: object
           required:
@@ -1477,7 +1469,7 @@ components:
       content:
         application/json:
           schema:
-            $ref: '#/components/schemas/Error'
+            $ref: "#/components/schemas/Error"
           example:
             success: false
             error:
@@ -1488,7 +1480,7 @@ components:
       content:
         application/json:
           schema:
-            $ref: '#/components/schemas/Error'
+            $ref: "#/components/schemas/Error"
           example:
             success: false
             error:
@@ -1499,7 +1491,7 @@ components:
       content:
         application/json:
           schema:
-            $ref: '#/components/schemas/Error'
+            $ref: "#/components/schemas/Error"
           example:
             success: false
             error:
@@ -1510,18 +1502,18 @@ components:
       content:
         application/json:
           schema:
-            $ref: '#/components/schemas/Error'
+            $ref: "#/components/schemas/Error"
           example:
             success: false
             error:
               code: CONFLICT
-              message: 'Share already exists (status: pending)'
+              message: "Share already exists (status: pending)"
     ValidationError:
       description: Validation error
       content:
         application/json:
           schema:
-            $ref: '#/components/schemas/Error'
+            $ref: "#/components/schemas/Error"
           example:
             success: false
             error: