From e26a85b9eb24993ecaff8266f2f5fd18aac4fa6d Mon Sep 17 00:00:00 2001
From: Joel Verhagen <jver@microsoft.com>
Date: Mon, 24 Aug 2026 10:07:17 -0400
Subject: [PATCH] Document staged package lifecycle status

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: e928b867-eb5b-4dff-a0ec-0fdcbe278846
---
 api/registry.npmjs.com/stage.yaml | 14 +++++++++++++-
 1 file changed, 13 insertions(+), 1 deletion(-)

diff --git a/api/registry.npmjs.com/stage.yaml b/api/registry.npmjs.com/stage.yaml
index 8bd88ea..fd5a3f0 100644
--- a/api/registry.npmjs.com/stage.yaml
+++ b/api/registry.npmjs.com/stage.yaml
@@ -5,7 +5,8 @@ paths:
         - Stage
       summary: Fetch a list of all staged package versions for the authenticated user.
       description: |
-        Retrieve staged package versions that are awaiting maintainer review.
+        Retrieve staged package versions that are undergoing automated validation or
+        awaiting maintainer review.
 
         This endpoint returns only items visible to the authenticated user. Results will be returned 
         in the order of most recently staged first in a descending order. Results are
@@ -74,6 +75,7 @@ paths:
                         actorType: "user"
                         access: "public"
                         shasum: "4f7f5f1d5bcf2f72f6e4d6c4f3b2812d8a2f6c19"
+                        status: "validating"
                       - id: "f8e7a45b-7a5f-4f31-8e6d-9dd1c6ef38c0"
                         packageName: "example-lib"
                         version: "0.4.0"
@@ -83,6 +85,7 @@ paths:
                         actorType: "trusted automation"
                         access: "private"
                         shasum: "8eb3b4e9b6e3d0d2c86be1e6d4f43f4be62e80ad"
+                        status: "staged"
                     page: 0
                     perPage: 10
                     total: 2
@@ -504,6 +507,15 @@ components:
         shasum:
           type: string
           description: The shasum of the package tarball.
+        status:
+          type: string
+          description: >
+            The staged package lifecycle status. `validating` means automated
+            review is still processing; `staged` means the version is ready for
+            maintainer review and approval.
+          enum:
+            - validating
+            - staged
     StagedPackumentRequest:
       type: object
       required: