@spacefast/common 0.0.26 → 0.2.2

package/dist/contracts/device-auth.js

@@ -1,15 +1,19 @@
 import { z } from "zod";
 import { AGENT_HANDOFF_DECLINE_REASONS } from "../docs/agent-setup.js";
-import { ApiKeyPresetSchema, ApiKeySchema } from "./api-keys.js";
+import { AccessProfileIdSchema, APPROVABLE_SCOPES, DEFAULT_ACCESS_PROFILE_ID, } from "./access-profiles.js";
+import { ApiKeySchema } from "./api-keys.js";
 import { DeviceTeamScopeSchema } from "./device-team-scope.js";
 export { DeviceTeamScopeSchema } from "./device-team-scope.js";
-// Device authorization flow (the platform spec Credential Bootstrap):
-// `POST /v1/auth/device` starts the flow, `POST /v1/auth/device/poll` redeems
-// it. Device codes are bearer capabilities: they ride POST bodies only, are
-// never logged, and redeem exactly once. User codes are short display codes the
-// person types on the dashboard verification page; verification attempts are
-// rate-limited per caller and per code with lockout so user codes cannot be
-// brute-forced into approving an attacker's device.
+// Device authorization flow (the platform spec Credential Bootstrap). Device
+// codes are bearer capabilities: body-only, never logged, redeemed once. User
+// code verification is rate-limited per caller and per code with lockout, so a
+// user code cannot be brute-forced into approving an attacker's device.
+// The one lifetime an interactive login grants — a single tier sized to
+// industry CLI/agent logins. The server (`grants.ts`) derives its TTL seconds
+// from these, and the approval page renders the same numbers, so the consent
+// screen can never state a lifetime the server won't honor.
+export const INTERACTIVE_GRANT_TTL_DAYS = 30;
+export const INTERACTIVE_GRANT_IDLE_DAYS = 7;
 export const DeviceAuthorizationStartRequestSchema = z
     .object({
     clientId: z
@@ -19,13 +23,7 @@ export const DeviceAuthorizationStartRequestSchema = z
         .max(255)
         .default("spacefast-cli")
         .describe("Requesting client identifier shown on the verification page."),
-    scope: z
-        .string()
-        .trim()
-        .min(1)
-        .max(4096)
-        .optional()
-        .describe("Requested access preset name. The approver chooses the final preset; this only seeds the verification page default."),
+    access: AccessProfileIdSchema.default(DEFAULT_ACCESS_PROFILE_ID).describe("Access profile the device requests. One word with a server-owned meaning; the approver can narrow the resulting scopes on the verification page but never widen them."),
     claim: z
         .object({
         spaceId: z
@@ -78,9 +76,20 @@ export const DeviceAuthorizationPollRequestSchema = z.object({
 export const DeviceAuthorizationStatusSchema = z
     .enum(["pending", "approved", "denied", "expired", "consumed"])
     .describe("Device authorization state. `approved` carries the one-time API key exactly once, then the record is `consumed`.");
+export const DeviceGrantedAccessSchema = z
+    .object({
+    profile: AccessProfileIdSchema.nullable().describe("Access profile the granted scopes exactly match, or null for a customized grant."),
+    scopes: z
+        .array(z.enum(APPROVABLE_SCOPES))
+        .min(1)
+        .describe("Exact scopes the approver granted. The one authoritative description."),
+    teams: DeviceTeamScopeSchema.describe("Team access the approver granted."),
+})
+    .strict();
 export const DeviceAuthorizationPollResponseSchema = z.object({
     status: DeviceAuthorizationStatusSchema,
     apiKey: ApiKeySchema.optional().describe("The minted API key including its one-time `secret`. Present only on the first poll after approval."),
+    access: DeviceGrantedAccessSchema.optional().describe("What was granted, in the words the approval page used. Present alongside `apiKey`."),
     claimedSpaceId: z
         .string()
         .nullable()
@@ -88,7 +97,7 @@ export const DeviceAuthorizationPollResponseSchema = z.object({
         .describe("Space claimed during approval, when the device flow was started by `sf spaces claim`."),
 });
 // Verification-page surface (`GET /v1/auth/device?user_code=…`). Returns
-// requester context only — never the device code (it is the bearer capability).
+// requester context only, never the device code.
 export const DeviceAuthorizationVerifyQuerySchema = z.object({
     user_code: z
         .string()
@@ -103,7 +112,15 @@ export const DeviceAuthorizationVerifyResponseSchema = z.object({
         .string()
         .nullable()
         .describe("Requesting client identifier recorded at device start."),
-    scope: z.string().nullable().describe("Access preset the device requested at start, if any."),
+    requestedAccess: z
+        .object({
+        profile: AccessProfileIdSchema.nullable().describe("Access profile the requested scopes exactly match, if any."),
+        scopes: z
+            .array(z.enum(APPROVABLE_SCOPES))
+            .describe("Scopes the device requested. The approval page renders exactly these."),
+    })
+        .strict()
+        .describe("Server-resolved access request. Ids only; copy is derived client-side."),
     origin: z
         .string()
         .nullable()
@@ -122,12 +139,18 @@ export const DeviceAuthorizationVerifyResponseSchema = z.object({
         .nullable()
         .describe("Explicit claim handoff attached to this device authorization, if any."),
 });
-// Approval intent (`POST /v1/auth/device/approve`): the approver chooses the
-// team scope and preset. If the device start request carried a claim handoff,
-// approval also claims that anonymous space into the explicit destination team after the approval CAS
-// wins. The intent persists server-side and the poll mints from it; the chosen
-// preset's compiled policy must be a subset of the approver's effective
-// team-role policy.
+// Approval intent (`POST /v1/auth/device/approve`). The intent persists
+// server-side and the poll mints from it.
+//
+// SCOPES are the wire vocabulary of the grant: the approver confirms (or
+// narrows) the same human-readable list that OAuth consent, the elevation
+// diff, and the ledger render. Access profiles are request intent only and are
+// never submitted here. Approved scopes must be a subset of the requested
+// scopes; authority is the granted scopes' actions bounded per team by the
+// holder's LIVE role at request time, so approval itself never fails on role.
+// A claim handoff is claimed into `claimTeamId` only after the approval CAS
+// wins.
+export const DeviceAuthorizationApprovalScopeSchema = z.enum(APPROVABLE_SCOPES);
 export const DeviceAuthorizationApproveRequestSchema = z
     .object({
     userCode: z
@@ -142,11 +165,14 @@ export const DeviceAuthorizationApproveRequestSchema = z
         .min(1)
         .optional()
         .describe("Explicit destination team for a claim handoff. Required when the flow carries a claim."),
-    preset: ApiKeyPresetSchema.describe("Policy preset for the minted key. Its compiled policy must be a subset of the approver's team-role policy."),
+    scopes: z
+        .array(DeviceAuthorizationApprovalScopeSchema)
+        .min(1)
+        .describe("OAuth scopes the approver granted — a subset of the scopes the device requested. Authority is these scopes' actions, bounded per team by the holder's live role on every request."),
     agentContinuation: z
         .boolean()
         .optional()
-        .describe("Applies when the device flow carries an anonymous-space claim: keep the publishing agent authorized after the claim (default false unless explicitly granted) via the one-time claim-token exchange."),
+        .describe("Applies when the device flow carries an anonymous-space claim. Keeps the publishing agent authorized after the claim through the one-time claim-token exchange. Defaults to false."),
 })
     .strict();
 export const DeviceAuthorizationApproveResponseSchema = z
@@ -170,31 +196,187 @@ export const DeviceAuthorizationDenyResponseSchema = z.object({
     status: z.literal("denied").describe("The device authorization is denied."),
 });
 export const AGENT_HANDOFF_CLIENT_TARGETS = ["claude-code", "codex", "cursor", "vscode"];
+export const PAGE_CONTEXT_HANDOFF_TARGETS = [
+    "any",
+    "v0",
+    "chatgpt",
+    "claude",
+    "t3",
+    "scira",
+    "cursor",
+];
+export const AGENT_HANDOFF_TARGETS = [
+    "claude-code",
+    "codex",
+    "cursor",
+    "vscode",
+    "any",
+    "v0",
+    "chatgpt",
+    "claude",
+    "t3",
+    "scira",
+];
+export function isAgentHandoffClientTarget(value) {
+    return AGENT_HANDOFF_CLIENT_TARGETS.some((target) => target === value);
+}
+export function isPageContextHandoffTarget(value) {
+    return PAGE_CONTEXT_HANDOFF_TARGETS.some((target) => target === value);
+}
+export const AGENT_HANDOFF_CLIENT_TARGET_LABELS = {
+    "claude-code": "Claude Code",
+    codex: "Codex",
+    cursor: "Cursor",
+    vscode: "VS Code",
+    // The target for a handoff copied without choosing an agent; the label reads
+    // naturally in the prompt's "Connect your agent privately" heading.
+    any: "your agent",
+    v0: "v0",
+    chatgpt: "ChatGPT",
+    claude: "Claude",
+    t3: "T3 Chat",
+    scira: "Scira",
+};
+/**
+ * Handoff purposes that name a subject: a Space to publish to, or the dashboard
+ * page the agent was launched from. Both are minted by a signed-in dashboard
+ * session, both appear in the team ledger, and both redeem for a credential.
+ */
+export const AGENT_HANDOFF_SUBJECT_KINDS = ["space", "page_context"];
+/**
+ * Every handoff purpose, including `anonymous` — the signed-out /start handoff.
+ * It has no team, no Space, and no subject: its document is the public setup
+ * guide and it can never be redeemed. It exists so a visitor who has not signed
+ * up yet still gets told when their agent picked the prompt up, which is exactly
+ * the capability the retired connect beacon provided. Being subject-less is what
+ * keeps it out of team ledgers and out of the revoke-all sweep.
+ */
+export const AGENT_HANDOFF_KINDS = [...AGENT_HANDOFF_SUBJECT_KINDS, "anonymous"];
+/** Wire-visible ceiling on how long an anonymous handoff stays fetchable. */
+export const ANONYMOUS_AGENT_HANDOFF_TTL_MS = 30 * 60_000;
+export const AnonymousAgentHandoffSchema = z
+    .object({
+    kind: z.literal("anonymous").describe("Handoff purpose."),
+    id: z.string().min(1).describe("Non-secret handoff ledger identifier."),
+    url: z
+        .string()
+        .url()
+        .describe("Sensitive one-time handoff URL. The only response field carrying the bearer."),
+    expiresAt: z
+        .string()
+        .datetime()
+        .describe("Instant after which the handoff stops serving its document."),
+})
+    .strict();
+export const AnonymousAgentHandoffStatusSchema = z
+    .object({
+    id: z.string().min(1).describe("Non-secret handoff ledger identifier."),
+    expiresAt: z
+        .string()
+        .datetime()
+        .describe("Instant after which the handoff stops serving its document."),
+    firstFetchedAt: z
+        .string()
+        .datetime()
+        .nullable()
+        .describe("Instant the document was first fetched, or null while nothing has fetched it."),
+    lastFetchedAt: z
+        .string()
+        .datetime()
+        .nullable()
+        .describe("Instant the document was most recently fetched, if it was."),
+    fetchCount: z.number().int().nonnegative().describe("Number of document fetches recorded."),
+})
+    .strict();
 export const AgentHandoffCreateRequestSchema = z
     .object({
-    teamId: z.string().min(1).describe("Team that owns the selected space."),
-    spaceId: z.string().min(1).describe("Finite space scope granted to the agent."),
+    kind: z
+        .enum(AGENT_HANDOFF_SUBJECT_KINDS)
+        .optional()
+        .describe("Handoff purpose. If absent, the purpose is `space`."),
+    teamId: z.string().min(1).describe("Team that owns the handoff."),
+    spaceId: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Space that the agent can manage. Use this field only for a `space` handoff."),
+    pagePath: z
+        .string()
+        .trim()
+        .startsWith("/")
+        .max(1024)
+        .optional()
+        .describe("Dashboard path that supplied the agent context. Use this field only for a `page_context` handoff."),
     clientTargetId: z
-        .enum(AGENT_HANDOFF_CLIENT_TARGETS)
-        .describe("CLI-redeemable client family the handoff is bound to."),
+        .enum(AGENT_HANDOFF_TARGETS)
+        .describe("Agent destination that receives the handoff prompt."),
 })
-    .strict();
+    .strict()
+    .superRefine((value, context) => {
+    const kind = value.kind ?? "space";
+    if (kind === "space" && !isAgentHandoffClientTarget(value.clientTargetId)) {
+        context.addIssue({
+            code: "custom",
+            path: ["clientTargetId"],
+            message: "A space handoff requires a local agent client.",
+        });
+    }
+    if (kind === "space" && !value.spaceId) {
+        context.addIssue({
+            code: "custom",
+            path: ["spaceId"],
+            message: "A space handoff requires spaceId.",
+        });
+    }
+    if (kind === "space" && value.pagePath) {
+        context.addIssue({
+            code: "custom",
+            path: ["pagePath"],
+            message: "A space handoff cannot include pagePath.",
+        });
+    }
+    if (kind === "page_context" && !value.pagePath) {
+        context.addIssue({
+            code: "custom",
+            path: ["pagePath"],
+            message: "A page-context handoff requires pagePath.",
+        });
+    }
+    if (kind === "page_context" && value.spaceId) {
+        context.addIssue({
+            code: "custom",
+            path: ["spaceId"],
+            message: "A page-context handoff cannot include spaceId.",
+        });
+    }
+});
 export const AgentHandoffCreateResponseSchema = z
     .object({
-    id: z.string().min(1).describe("Opaque app-private handoff document identifier."),
+    kind: z.enum(AGENT_HANDOFF_SUBJECT_KINDS).describe("Handoff purpose."),
+    id: z.string().min(1).describe("Non-secret handoff ledger identifier."),
     url: z
         .string()
         .url()
-        .describe("Sensitive one-time handoff URL. This is the only response field containing the browser credential."),
+        .describe("Sensitive one-time handoff URL. The only response field carrying the browser credential."),
     expiresAt: z
         .string()
         .datetime()
         .describe("Instant after which the handoff cannot be redeemed."),
-    teamId: z.string().min(1).describe("Team that owns the selected space."),
-    spaceId: z.string().min(1).describe("Finite space scope granted to the agent."),
+    teamId: z.string().min(1).describe("Team that owns the handoff."),
+    spaceId: z
+        .string()
+        .min(1)
+        .nullable()
+        .describe("Space that the agent can manage. A page-context handoff returns null."),
+    pagePath: z
+        .string()
+        .startsWith("/")
+        .max(1024)
+        .nullable()
+        .describe("Dashboard path that supplied the agent context. A space handoff returns null."),
     clientTargetId: z
-        .enum(AGENT_HANDOFF_CLIENT_TARGETS)
-        .describe("CLI-redeemable client family the handoff is bound to."),
+        .enum(AGENT_HANDOFF_TARGETS)
+        .describe("Agent destination that receives the handoff prompt."),
 })
     .strict();
 export const AgentHandoffRedeemRequestSchema = z
@@ -204,20 +386,31 @@ export const AgentHandoffRedeemRequestSchema = z
         .min(1)
         .describe("Full sensitive handoff link, supplied only in the request body."),
     clientTargetId: z
-        .enum(AGENT_HANDOFF_CLIENT_TARGETS)
+        .enum(AGENT_HANDOFF_TARGETS)
         .optional()
-        .describe("Declared redeeming client family, when the client can identify itself."),
+        .describe("Agent destination declared by the client, if the client knows it."),
 })
     .strict();
 export const AgentHandoffRedeemResponseSchema = z
     .object({
     status: z.literal("redeemed").describe("The handoff was redeemed exactly once."),
-    apiKey: ApiKeySchema.describe("Finite space-scoped API key including its one-time secret."),
-    teamId: z.string().min(1).describe("Team that owns the selected space."),
-    spaceId: z.string().min(1).describe("Finite space scope granted to the agent."),
+    kind: z.enum(AGENT_HANDOFF_SUBJECT_KINDS).describe("Handoff purpose."),
+    apiKey: ApiKeySchema.describe("API key that includes its one-time secret."),
+    teamId: z.string().min(1).describe("Team that owns the handoff."),
+    spaceId: z
+        .string()
+        .min(1)
+        .nullable()
+        .describe("Space that the agent can manage. A page-context handoff returns null."),
+    pagePath: z
+        .string()
+        .startsWith("/")
+        .max(1024)
+        .nullable()
+        .describe("Dashboard path that supplied the agent context. A space handoff returns null."),
     clientTargetId: z
-        .enum(AGENT_HANDOFF_CLIENT_TARGETS)
-        .describe("CLI-redeemable client family the handoff is bound to."),
+        .enum(AGENT_HANDOFF_TARGETS)
+        .describe("Agent destination that received the handoff prompt."),
 })
     .strict();
 export const AgentHandoffRevokeResponseSchema = z
@@ -225,11 +418,10 @@ export const AgentHandoffRevokeResponseSchema = z
     status: z.literal("revoked").describe("The unused handoff is revoked."),
 })
     .strict();
-// List (`GET /v1/auth/agent-handoffs?teamId=…`): the human handoff ledger. Session-only,
-// scoped to one team, bounded to the newest rows (active handoffs are few and short-lived,
-// so the bound can never hide a revocable link); rows are the truthful lifecycle record,
-// never the secret (the browser credential exists only in the one create response and is
-// never listed or replayed).
+// List (`GET /v1/auth/agent-handoffs?teamId=…`). Session-only, one team,
+// bounded to the newest rows; handoffs are few and short-lived, so the bound
+// cannot hide a revocable link. The browser credential exists only in the
+// create response and is never listed.
 export const AgentHandoffListQuerySchema = z.object({
     teamId: z.string().min(1).describe("Team whose issued agent handoffs to list."),
 });
@@ -238,12 +430,23 @@ export const AgentHandoffStatusSchema = z
     .describe("Stored lifecycle status. `expired` is not a stored status. The caller derives it from `expiresAt`.");
 export const AgentHandoffSummarySchema = z
     .object({
-    id: z.string().min(1).describe("Opaque app-private handoff document identifier."),
-    teamId: z.string().min(1).describe("Team that owns the selected space."),
-    spaceId: z.string().min(1).describe("Finite space scope granted to the agent."),
+    kind: z.enum(AGENT_HANDOFF_SUBJECT_KINDS).describe("Handoff purpose."),
+    id: z.string().min(1).describe("Non-secret handoff ledger identifier."),
+    teamId: z.string().min(1).describe("Team that owns the handoff."),
+    spaceId: z
+        .string()
+        .min(1)
+        .nullable()
+        .describe("Space that the agent can manage. A page-context handoff returns null."),
+    pagePath: z
+        .string()
+        .startsWith("/")
+        .max(1024)
+        .nullable()
+        .describe("Dashboard path that supplied the agent context. A space handoff returns null."),
     clientTargetId: z
-        .enum(AGENT_HANDOFF_CLIENT_TARGETS)
-        .describe("CLI-redeemable client family the handoff is bound to."),
+        .enum(AGENT_HANDOFF_TARGETS)
+        .describe("Agent destination that received the handoff prompt."),
     status: AgentHandoffStatusSchema,
     createdAt: z.string().datetime().describe("Instant the handoff was minted."),
     expiresAt: z
@@ -260,6 +463,17 @@ export const AgentHandoffSummarySchema = z
         .datetime()
         .nullable()
         .describe("Instant the handoff was revoked, if it was."),
+    firstFetchedAt: z
+        .string()
+        .datetime()
+        .nullable()
+        .describe("Instant the handoff document was first fetched, if it was."),
+    lastFetchedAt: z
+        .string()
+        .datetime()
+        .nullable()
+        .describe("Instant the handoff document was most recently fetched, if it was."),
+    fetchCount: z.number().int().nonnegative().describe("Number of document fetches recorded."),
 })
     .strict();
 export const AgentHandoffListResponseSchema = z.array(AgentHandoffSummarySchema);

package/dist/contracts/docs.d.ts

@@ -1,5 +1,4 @@
 import { z } from "zod";
-/** Disclosure tiers an entry can carry, default `essential` for listings. */
 export declare const DOC_TIERS: readonly ["essential", "full", "reference"];
 export declare const docsIndexQuerySchema: z.ZodObject<{
     q: z.ZodOptional<z.ZodString>;
@@ -11,18 +10,16 @@ export declare const docsIndexQuerySchema: z.ZodObject<{
     category: z.ZodOptional<z.ZodEnum<{
         guide: "guide";
         api: "api";
-        error: "error";
         cli: "cli";
+        error: "error";
         workflow: "workflow";
         recipe: "recipe";
     }>>;
 }, z.core.$strip>;
-/** Links carried by every docs entry. */
 export declare const DocsLinksSchema: z.ZodObject<{
     doc: z.ZodString;
     self: z.ZodString;
 }, z.core.$strip>;
-/** One entry in the docs index. */
 export declare const DocsEntrySchema: z.ZodObject<{
     slug: z.ZodString;
     title: z.ZodString;
@@ -30,8 +27,8 @@ export declare const DocsEntrySchema: z.ZodObject<{
     category: z.ZodEnum<{
         guide: "guide";
         api: "api";
-        error: "error";
         cli: "cli";
+        error: "error";
         workflow: "workflow";
         recipe: "recipe";
     }>;
@@ -48,7 +45,6 @@ export declare const DocsEntrySchema: z.ZodObject<{
     }, z.core.$strip>;
 }, z.core.$strip>;
 export type DocsEntry = z.infer<typeof DocsEntrySchema>;
-/** A single doc, which additionally carries its printable body. */
 export declare const DocsDocSchema: z.ZodObject<{
     slug: z.ZodString;
     title: z.ZodString;
@@ -56,8 +52,8 @@ export declare const DocsDocSchema: z.ZodObject<{
     category: z.ZodEnum<{
         guide: "guide";
         api: "api";
-        error: "error";
         cli: "cli";
+        error: "error";
         workflow: "workflow";
         recipe: "recipe";
     }>;
@@ -75,7 +71,7 @@ export declare const DocsDocSchema: z.ZodObject<{
     body: z.ZodString;
 }, z.core.$strip>;
 export type DocsDoc = z.infer<typeof DocsDocSchema>;
-/** The GET /v1/docs index payload (inside the `{ data }` envelope). */
+/** GET /v1/docs payload, inside the `{ data }` envelope. */
 export declare const DocsIndexResponseSchema: z.ZodObject<{
     tier: z.ZodEnum<{
         essential: "essential";
@@ -86,8 +82,8 @@ export declare const DocsIndexResponseSchema: z.ZodObject<{
     category: z.ZodNullable<z.ZodEnum<{
         guide: "guide";
         api: "api";
-        error: "error";
         cli: "cli";
+        error: "error";
         workflow: "workflow";
         recipe: "recipe";
     }>>;
@@ -99,8 +95,8 @@ export declare const DocsIndexResponseSchema: z.ZodObject<{
         category: z.ZodEnum<{
             guide: "guide";
             api: "api";
-            error: "error";
             cli: "cli";
+            error: "error";
             workflow: "workflow";
             recipe: "recipe";
         }>;

package/dist/contracts/docs.js

@@ -1,17 +1,12 @@
-// Public contract for the machine-readable docs index API (GET /v1/docs and
-// GET /v1/docs/:slug). Tier values come from the shared CLI disclosure tiers and
-// categories from the shared docs catalog, so the API can never describe a tier
-// or category the catalog does not produce.
+// Public contract for the docs index API (GET /v1/docs, GET /v1/docs/pages/:slug).
+// Tiers and categories are reused from the shared CLI vocabulary and docs
+// catalog, so the API can never name one they do not produce.
 import { z } from "zod";
 import { DOC_KINDS } from "../docs/catalog.js";
 import { CLI_DISCLOSURE_TIER_ORDER } from "../vocabulary.js";
-/** Disclosure tiers an entry can carry, default `essential` for listings. */
 export const DOC_TIERS = CLI_DISCLOSURE_TIER_ORDER;
 const docTierEnum = z.enum([...DOC_TIERS]);
 const docCategoryEnum = z.enum([...DOC_KINDS]);
-// Query for GET /v1/docs. Tier-aware: defaults to `essential`; pass
-// `tier=reference` to get EVERYTHING (tiers are cumulative). Optional `q`
-// free-text search and `category` filter compose with the tier.
 export const docsIndexQuerySchema = z.object({
     q: z.string().optional().describe("Free-text search across slug, title, summary, and keywords."),
     tier: docTierEnum
@@ -21,12 +16,10 @@ export const docsIndexQuerySchema = z.object({
         .optional()
         .describe("Restrict to one docs area: `guide`, `cli`, `api`, `recipe`, `workflow`, or `error`."),
 });
-/** Links carried by every docs entry. */
 export const DocsLinksSchema = z.object({
     doc: z.string().url().describe("Canonical human-readable docs URL."),
-    self: z.string().describe("API-relative link to this entry's JSON (`/v1/docs/{slug}`)."),
+    self: z.string().describe("API-relative link to this entry's JSON (`/v1/docs/pages/{slug}`)."),
 });
-/** One entry in the docs index. */
 export const DocsEntrySchema = z.object({
     slug: z.string().describe("Stable topic id, for example `publishing` or `api/spaces`."),
     title: z.string(),
@@ -37,11 +30,10 @@ export const DocsEntrySchema = z.object({
     url: z.string().url().describe("Canonical human-readable docs URL."),
     links: DocsLinksSchema,
 });
-/** A single doc, which additionally carries its printable body. */
 export const DocsDocSchema = DocsEntrySchema.extend({
     body: z.string().describe("Short printable explanation of the topic."),
 });
-/** The GET /v1/docs index payload (inside the `{ data }` envelope). */
+/** GET /v1/docs payload, inside the `{ data }` envelope. */
 export const DocsIndexResponseSchema = z.object({
     tier: docTierEnum.describe("The tier the listing ran at."),
     query: z.string().nullable().describe("The trimmed `q` query, or null when listing."),