@phnx-labs/agents-cli 1.22.46 → 1.22.49

package/dist/lib/share/backend.js

@@ -0,0 +1,139 @@
+/**
+ * ShareBackend — the token-source seam for `agents artifacts share`.
+ *
+ * Two legitimate principals, picked once at publish time:
+ *   - **managed**: the caller is signed in to Phoenix (`readSession()`), no
+ *     explicit BYO override. Token is the Phoenix access_token; endpoint is
+ *     the already-live `share.agents-cli.sh`. Zero Cloudflare setup.
+ *   - **byo**: the existing static WRITE_TOKEN path (`readShareConfig()` +
+ *     `readWriteToken()`). Unchanged for power users / custom domains / fleet
+ *     injection of `SHARE_WRITE_TOKEN`.
+ *
+ * Dispatch is not a fallback: signed-in AND no BYO override → managed;
+ * otherwise BYO. Fail loud when neither principal can authenticate.
+ *
+ * Explicit BYO override (any one is enough):
+ *   - `opts.byo === true`
+ *   - `opts.writeToken` (a caller-supplied static token, including tests)
+ *   - `AGENTS_SHARE_BACKEND=byo`
+ */
+import { PHOENIX_ID_BASE, readSession } from '../identity/client.js';
+import { DEFAULT_SHARE_DOMAIN, readShareConfig, readWriteToken, readWriteTokenEnv, } from './config.js';
+/** Env var that forces the BYO path. Value must be exactly `byo`. */
+export const SHARE_BACKEND_ENV = 'AGENTS_SHARE_BACKEND';
+/** URL-safe namespace: lowercase `[a-z0-9-]+`. Matches the Worker's sanitize.
+ *
+ * This is URL-safety, not collision-resistance: two values that differ only
+ * in case or punctuation share a prefix. */
+export function sanitizeShareNamespace(s) {
+    return s.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+}
+/**
+ * Public managed-share handle from a verified email.
+ *
+ * `muqsitnawaz@gmail.com` → `muqsitnawaz`. Plus-tags are dropped
+ * (`muqsitnawaz+dev@gmail.com` → `muqsitnawaz`) so the URL stays the
+ * account's default name. Empty / missing email → `''` (caller falls
+ * back to userId). Must match the Worker `handleFromEmail`.
+ */
+export function handleFromEmail(email) {
+    if (!email)
+        return '';
+    const local = email.split('@')[0] ?? '';
+    const beforePlus = local.split('+')[0] ?? local;
+    return sanitizeShareNamespace(beforePlus);
+}
+/** Managed URL namespace: email handle, else sanitized userId (never empty if either is set). */
+export function managedShareHandle(session) {
+    return handleFromEmail(session.email) || sanitizeShareNamespace(session.userId ?? '');
+}
+export function managedShareBaseUrl() {
+    return `https://${DEFAULT_SHARE_DOMAIN}`;
+}
+function shareEndpointHost(value) {
+    return value.replace(/^https?:\/\//i, '').replace(/\/+$/, '').toLowerCase();
+}
+/**
+ * True when this config is the platform managed endpoint (`share.agents-cli.sh`).
+ * The deploy path uses this — not "the caller is signed in" — to decide whether
+ * to bind `PHOENIX_ID_BASE` on the Worker.
+ */
+export function isManagedShareEndpoint(cfg) {
+    const managedHost = DEFAULT_SHARE_DOMAIN.toLowerCase();
+    if (cfg.domain && shareEndpointHost(cfg.domain) === managedHost)
+        return true;
+    if (cfg.baseUrl && shareEndpointHost(cfg.baseUrl) === managedHost)
+        return true;
+    return false;
+}
+/**
+ * Phoenix ID URL to bind on a managed Worker deploy. `undefined` for a
+ * pure-BYO Worker (WRITE_TOKEN only). Fail loud if this is a managed deploy
+ * but the base is empty — never skip-set a blank secret.
+ */
+export function phoenixIdBaseForDeploy(opts = {}, cfg) {
+    const managed = opts.managed === true || (cfg != null && isManagedShareEndpoint(cfg));
+    if (!managed)
+        return undefined;
+    const base = PHOENIX_ID_BASE.replace(/\/+$/, '').trim();
+    if (!base) {
+        throw new Error('Managed share deploy requires PHOENIX_ID_BASE so the Worker can verify Phoenix bearers. Set the PHOENIX_ID_BASE env var.');
+    }
+    return base;
+}
+/**
+ * Pick the principal. Signed-in (`readSession() != null`) AND no explicit BYO
+ * override → managed; otherwise BYO.
+ */
+export function shouldUseManaged(opts = {}) {
+    if (opts.byo === true)
+        return false;
+    if (opts.writeToken)
+        return false;
+    if ((process.env[SHARE_BACKEND_ENV] ?? '').trim().toLowerCase() === 'byo')
+        return false;
+    const session = opts.session === undefined ? readSession() : opts.session;
+    return session != null;
+}
+export function resolveShareBackend(opts = {}) {
+    if (shouldUseManaged(opts)) {
+        const session = opts.session === undefined ? readSession() : opts.session;
+        if (!session) {
+            throw new Error("Not signed in. Run 'agents auth login'.");
+        }
+        return resolveManagedBackend(session);
+    }
+    return resolveByoBackend(opts);
+}
+function resolveManagedBackend(session) {
+    if (!session.access_token) {
+        throw new Error("Not signed in. Run 'agents auth login'.");
+    }
+    const namespace = managedShareHandle(session);
+    if (!namespace) {
+        throw new Error("Signed in but the session has no email or user id. Run 'agents auth login' again.");
+    }
+    return {
+        kind: 'managed',
+        baseUrl: managedShareBaseUrl(),
+        token: session.access_token,
+        namespace,
+    };
+}
+function resolveByoBackend(opts) {
+    const cfg = opts.config ?? readShareConfig();
+    if (!cfg) {
+        throw new Error("Not set up yet. Run 'agents auth login' to publish on the managed endpoint (zero Cloudflare setup), or 'agents artifacts setup' / 'agents artifacts share join' for your own Cloudflare.");
+    }
+    const token = opts.writeToken ??
+        (opts.requireToken === false ? (readWriteTokenEnv() ?? '') : readWriteToken());
+    // Namespace is the GitHub username. An explicit --github-user is sanitized
+    // here; otherwise publish fills it via resolveShareUsername (gh/git config).
+    const namespace = opts.githubUser ? sanitizeShareNamespace(opts.githubUser) : '';
+    return {
+        kind: 'byo',
+        baseUrl: cfg.baseUrl.replace(/\/+$/, ''),
+        token,
+        namespace,
+    };
+}

package/dist/lib/share/delete.d.ts

@@ -68,7 +68,7 @@ export interface DeleteShareOptions {
     /** Skip deleting the target's retained revisions (`<key>/rev-*`, RUSH-2683
      * revision retention) — default: delete them too. A republished-then-deleted
      * share would otherwise leave its prior world-readable versions live for up
-     * to the bucket's lifecycle max-age (see docs/share.md §Revisions). */
+     * to the bucket's lifecycle max-age (see docs/distribution.md). */
     keepRevisions?: boolean;
     /** Treat an already-missing target as a no-op success instead of an error
      * (mirrors SQL's `DROP ... IF EXISTS`). Default: missing target is an error. */
@@ -77,8 +77,12 @@ export interface DeleteShareOptions {
     githubUser?: string;
     /** DI seam for tests — override the persisted share endpoint config. */
     config?: ShareConfig;
-    /** DI seam for tests — override the keychain-backed write token. */
+    /** DI seam for tests — override the keychain-backed write token. Selects BYO. */
     writeToken?: string;
+    /** DI seam for tests — override `readSession()`. `null` means signed out. */
+    session?: import('../identity/client.js').PhoenixSession | null;
+    /** Force the BYO Cloudflare path even when signed in. */
+    byo?: boolean;
     /** DI seam for tests — override the real HTTP DELETE. */
     deleter?: DeleteFn;
     /** DI seam for tests — override the real HTTP existence check. */

package/dist/lib/share/delete.js

@@ -7,7 +7,7 @@
 // returns `{"ok":true}` — so `{"ok":true}` alone is never proof of a takedown.
 // Every delete here is followed by a status check that must observe 404 before
 // the operation is reported as successful.
-import { readShareConfig, readWriteToken } from './config.js';
+import { resolveShareBackend } from './backend.js';
 import { buildShareKey, resolveShareUsername } from './publish.js';
 /**
  * Normalize any of the three accepted target forms to the R2 key that publish
@@ -103,7 +103,7 @@ export async function deleteObject(endpoint, key, opts = {}) {
     const existedBefore = before.status !== 404;
     const r = await del(url, { authorization: `Bearer ${endpoint.token}` });
     if (!r.ok) {
-        throw new Error(`Delete failed (${r.status}) for ${url}. Check the write token, or that 'agents artifacts setup' completed.`);
+        throw new Error(`Delete failed (${r.status}) for ${url}. Check the bearer (Phoenix session or WRITE_TOKEN), or that 'agents artifacts setup' completed.`);
     }
     const after = await check(url);
     const verified404 = after.status === 404;
@@ -113,13 +113,12 @@ export async function deleteObject(endpoint, key, opts = {}) {
  * are gone. Throws on an unverified takedown — never reports success for an
  * object that still resolves. */
 export async function deleteShare(target, opts = {}) {
-    const cfg = opts.config ?? readShareConfig();
-    if (!cfg) {
-        throw new Error("Not set up yet. Run 'agents artifacts setup' (provision your own endpoint) or 'agents artifacts share join' (use an existing one).");
-    }
-    const token = opts.writeToken ?? readWriteToken();
-    const resolved = await resolveDeleteTarget(target, { githubUser: opts.githubUser });
-    const endpoint = { baseUrl: cfg.baseUrl, token };
+    const backend = resolveShareBackend(opts);
+    const githubUser = backend.kind === 'managed'
+        ? backend.namespace
+        : opts.githubUser || backend.namespace || undefined;
+    const resolved = await resolveDeleteTarget(target, { githubUser });
+    const endpoint = { baseUrl: backend.baseUrl, token: backend.token };
     const page = await deleteObject(endpoint, resolved.key, { deleter: opts.deleter, checker: opts.checker });
     if (!page.existedBefore) {
         if (opts.ifExists) {

package/dist/lib/share/html.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Make an HTML page self-contained enough to view on share.agents-cli.sh.
+ *
+ * Chrome "Save as" (and some renderers) leave `file:///…html#section` TOC
+ * links and sibling image paths. Those work on disk and 404 on the share
+ * Worker, which only stores the one PUT body. Rewrite same-document file
+ * anchors to `#section`, and inline local image files as data URIs.
+ *
+ * https citations, data: URIs already in the page, and missing files are
+ * left alone. This is not a bundler — it only fixes what would otherwise
+ * render as a broken page after a single-file publish.
+ */
+/** Skip inlining a sibling that would bloat the page past a reasonable PUT. */
+export declare const MAX_INLINE_BYTES: number;
+/**
+ * `href="file:///tmp/page.html#purpose"` → `href="#purpose"`.
+ * Bare `file:///tmp/page.html` (no hash) becomes `href="#"`.
+ */
+export declare function rewriteFileAnchors(html: string): string;
+/** Replace local image src/href with a data URI when the file exists next to the page. */
+export declare function inlineLocalAssets(html: string, htmlPath: string): string;
+export declare function prepareShareHtml(html: string, htmlPath: string): string;

package/dist/lib/share/html.js

@@ -0,0 +1,88 @@
+/**
+ * Make an HTML page self-contained enough to view on share.agents-cli.sh.
+ *
+ * Chrome "Save as" (and some renderers) leave `file:///…html#section` TOC
+ * links and sibling image paths. Those work on disk and 404 on the share
+ * Worker, which only stores the one PUT body. Rewrite same-document file
+ * anchors to `#section`, and inline local image files as data URIs.
+ *
+ * https citations, data: URIs already in the page, and missing files are
+ * left alone. This is not a bundler — it only fixes what would otherwise
+ * render as a broken page after a single-file publish.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, extname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/** Skip inlining a sibling that would bloat the page past a reasonable PUT. */
+export const MAX_INLINE_BYTES = 4 * 1024 * 1024;
+const IMAGE_MIME = {
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif',
+    '.webp': 'image/webp',
+    '.svg': 'image/svg+xml',
+    '.ico': 'image/x-icon',
+    '.avif': 'image/avif',
+};
+/**
+ * `href="file:///tmp/page.html#purpose"` → `href="#purpose"`.
+ * Bare `file:///tmp/page.html` (no hash) becomes `href="#"`.
+ */
+export function rewriteFileAnchors(html) {
+    return html.replace(/\b(href\s*=\s*["'])file:\/\/[^"'#]*(#[^"']*)?(["'])/gi, (_m, attr, hash, quote) => `${attr}${hash ?? '#'}${quote}`);
+}
+function isRemoteOrSpecial(url) {
+    return (url.startsWith('data:') ||
+        url.startsWith('http://') ||
+        url.startsWith('https://') ||
+        url.startsWith('//') ||
+        url.startsWith('#') ||
+        url.startsWith('mailto:') ||
+        url.startsWith('javascript:') ||
+        url.startsWith('agents:'));
+}
+function localImagePath(url, htmlDir) {
+    if (!url || isRemoteOrSpecial(url))
+        return null;
+    const withoutHash = url.split('#')[0] ?? url;
+    let fsPath;
+    if (withoutHash.startsWith('file:')) {
+        try {
+            fsPath = fileURLToPath(withoutHash);
+        }
+        catch {
+            return null;
+        }
+    }
+    else {
+        fsPath = resolve(htmlDir, withoutHash);
+    }
+    if (!existsSync(fsPath))
+        return null;
+    const mime = IMAGE_MIME[extname(fsPath).toLowerCase()];
+    if (!mime)
+        return null;
+    return { path: fsPath, mime };
+}
+/** Replace local image src/href with a data URI when the file exists next to the page. */
+export function inlineLocalAssets(html, htmlPath) {
+    const dir = dirname(htmlPath);
+    return html.replace(/\b((?:src|href)\s*=\s*["'])([^"']+)(["'])/gi, (full, pre, url, post) => {
+        const local = localImagePath(url, dir);
+        if (!local)
+            return full;
+        try {
+            const buf = readFileSync(local.path);
+            if (buf.length > MAX_INLINE_BYTES)
+                return full;
+            return `${pre}data:${local.mime};base64,${buf.toString('base64')}${post}`;
+        }
+        catch {
+            return full;
+        }
+    });
+}
+export function prepareShareHtml(html, htmlPath) {
+    return inlineLocalAssets(rewriteFileAnchors(html), htmlPath);
+}

package/dist/lib/share/provision.d.ts

@@ -61,6 +61,18 @@ export interface UpdateWorkerResult {
     /** True when the upload was skipped because `previousHash` already matched. */
     skipped: boolean;
 }
+/** Cloudflare `secret_text` name the Worker reads as `env.PHOENIX_ID_BASE`. */
+export declare const WORKER_PHOENIX_ID_BASE_SECRET = "PHOENIX_ID_BASE";
+export type UpdateWorkerOpts = ProvisionOptions & {
+    force?: boolean;
+    /**
+     * Phoenix ID base URL to bind as `PHOENIX_ID_BASE` after the script upload.
+     * Pass this for a managed deployment; omit it for a pure-BYO Worker (which
+     * authenticates only via WRITE_TOKEN). An empty string is a caller bug and
+     * fails loud — do not pass a blank to "skip".
+     */
+    phoenixIdBase?: string;
+};
 /**
  * Re-deploy the Worker script against an ALREADY-provisioned endpoint (same
  * account/worker/bucket `deployWorker` was first called with) and idempotently
@@ -78,7 +90,9 @@ export interface UpdateWorkerResult {
  * API right after the upload — the same two-call sequence first-time
  * provisioning already uses (`deployWorker` then `setWorkerSecret`), except
  * `writeToken` here is the caller's EXISTING token, never a freshly generated
- * one. Cloudflare's own docs describe exactly this "secrets survive a
+ * one. A managed deploy also re-applies `PHOENIX_ID_BASE` the same way (the
+ * Worker reads it to verify Phoenix bearers); a pure-BYO deploy omits it.
+ * Cloudflare's own docs describe exactly this "secrets survive a
  * subsequent write" contract for the sibling `wrangler versions upload
  * --secrets-file` flow ("Secrets not included in the file are preserved from
  * the previous version" —
@@ -86,9 +100,9 @@ export interface UpdateWorkerResult {
  * re-setting the secret to its own value after every deploy gets the same
  * outcome without depending on an unverified upload-time flag.
  */
-export declare function updateWorker(apiToken: string, accountId: string, workerName: string, bucketName: string, script: string, writeToken: string, previousHash: string | undefined, opts?: ProvisionOptions & {
-    force?: boolean;
-}): Promise<UpdateWorkerResult>;
+export declare function updateWorker(apiToken: string, accountId: string, workerName: string, bucketName: string, script: string, writeToken: string, previousHash: string | undefined, opts?: UpdateWorkerOpts): Promise<UpdateWorkerResult>;
+/** Add/update a secret_text binding using Cloudflare's Workers Secrets API. */
+export declare function putWorkerSecret(apiToken: string, accountId: string, workerName: string, name: string, text: string, opts?: ProvisionOptions): Promise<void>;
 /** Add/update the WRITE_TOKEN binding using Cloudflare's Workers Secrets API. */
 export declare function setWorkerSecret(apiToken: string, accountId: string, workerName: string, writeToken: string, opts?: ProvisionOptions): Promise<void>;
 /** Enable the free `*.workers.dev` route for the script, and return the account subdomain. */

package/dist/lib/share/provision.js

@@ -101,6 +101,8 @@ export async function deployWorker(apiToken, accountId, workerName, script, buck
 export function hashWorkerScript(script) {
     return createHash('sha256').update(script, 'utf8').digest('hex');
 }
+/** Cloudflare `secret_text` name the Worker reads as `env.PHOENIX_ID_BASE`. */
+export const WORKER_PHOENIX_ID_BASE_SECRET = 'PHOENIX_ID_BASE';
 /**
  * Re-deploy the Worker script against an ALREADY-provisioned endpoint (same
  * account/worker/bucket `deployWorker` was first called with) and idempotently
@@ -118,7 +120,9 @@ export function hashWorkerScript(script) {
  * API right after the upload — the same two-call sequence first-time
  * provisioning already uses (`deployWorker` then `setWorkerSecret`), except
  * `writeToken` here is the caller's EXISTING token, never a freshly generated
- * one. Cloudflare's own docs describe exactly this "secrets survive a
+ * one. A managed deploy also re-applies `PHOENIX_ID_BASE` the same way (the
+ * Worker reads it to verify Phoenix bearers); a pure-BYO deploy omits it.
+ * Cloudflare's own docs describe exactly this "secrets survive a
  * subsequent write" contract for the sibling `wrangler versions upload
  * --secrets-file` flow ("Secrets not included in the file are preserved from
  * the previous version" —
@@ -129,6 +133,13 @@ export function hashWorkerScript(script) {
 export async function updateWorker(apiToken, accountId, workerName, bucketName, script, writeToken, previousHash, opts = {}) {
     const templateHash = hashWorkerScript(script);
     if (!opts.force && previousHash === templateHash) {
+        // Script is current so we skip the upload (which would wipe secrets). A
+        // managed Worker still needs PHOENIX_ID_BASE present — a prior upload from
+        // a CLI that never set it left the secret missing, and this is the heal
+        // that does not require --force or a dummy template bump.
+        if (opts.phoenixIdBase !== undefined) {
+            await applyPhoenixIdBaseSecret(apiToken, accountId, workerName, opts.phoenixIdBase, opts);
+        }
         return { templateHash, skipped: true };
     }
     await deployWorker(apiToken, accountId, workerName, script, bucketName, opts);
@@ -143,18 +154,41 @@ export async function updateWorker(apiToken, accountId, workerName, bucketName,
         const detail = e instanceof Error ? e.message : String(e);
         throw new Error(`Worker deployed but the write token failed to re-apply — re-run \`agents artifacts share update\` to fix this before publishing/deleting anything. (${detail})`);
     }
+    if (opts.phoenixIdBase !== undefined) {
+        try {
+            await applyPhoenixIdBaseSecret(apiToken, accountId, workerName, opts.phoenixIdBase, opts);
+        }
+        catch (e) {
+            const detail = e instanceof Error ? e.message : String(e);
+            throw new Error(`Worker deployed but PHOENIX_ID_BASE failed to re-apply — Phoenix-bearer publishes will 401 until you re-run \`agents artifacts share update\`. (${detail})`);
+        }
+    }
     return { templateHash, skipped: false };
 }
-/** Add/update the WRITE_TOKEN binding using Cloudflare's Workers Secrets API. */
-export async function setWorkerSecret(apiToken, accountId, workerName, writeToken, opts = {}) {
+/** Add/update a secret_text binding using Cloudflare's Workers Secrets API. */
+export async function putWorkerSecret(apiToken, accountId, workerName, name, text, opts = {}) {
     const request = opts.request ?? defaultCloudflareRequester;
     await request({
         apiToken,
         method: 'PUT',
         pathname: `/accounts/${accountId}/workers/scripts/${workerName}/secrets`,
-        body: { name: 'WRITE_TOKEN', text: writeToken, type: 'secret_text' },
+        body: { name, text, type: 'secret_text' },
     });
 }
+/** Add/update the WRITE_TOKEN binding using Cloudflare's Workers Secrets API. */
+export async function setWorkerSecret(apiToken, accountId, workerName, writeToken, opts = {}) {
+    await putWorkerSecret(apiToken, accountId, workerName, 'WRITE_TOKEN', writeToken, opts);
+}
+function normalizePhoenixIdBase(phoenixIdBase) {
+    const base = phoenixIdBase.replace(/\/+$/, '').trim();
+    if (!base) {
+        throw new Error('Managed share deploy requires a non-empty PHOENIX_ID_BASE so the Worker can verify Phoenix bearers. Set the PHOENIX_ID_BASE env var.');
+    }
+    return base;
+}
+async function applyPhoenixIdBaseSecret(apiToken, accountId, workerName, phoenixIdBase, opts = {}) {
+    await putWorkerSecret(apiToken, accountId, workerName, WORKER_PHOENIX_ID_BASE_SECRET, normalizePhoenixIdBase(phoenixIdBase), opts);
+}
 /** Enable the free `*.workers.dev` route for the script, and return the account subdomain. */
 export async function enableWorkersDev(apiToken, accountId, workerName, opts = {}) {
     const request = opts.request ?? defaultCloudflareRequester;

package/dist/lib/share/publish.d.ts

@@ -18,10 +18,18 @@ export interface PublishOptions {
      */
     expire?: string;
     contentType?: string;
+    /**
+     * Server-enforced visibility (RUSH-3135). `public` (default) is listed in
+     * the gallery; `unlisted` is a capability URL (GET still 200, X-Robots-Tag:
+     * noindex, hidden from gallery/list). `org` is Phase 2 — the Worker 400s it.
+     */
+    visibility?: ShareVisibility;
     /**
      * Hide this page from the public `/<user>` gallery and `agents artifacts share list`
      * (metadata `visibility=unlisted`). The direct URL is still world-readable —
-     * unlisted, not secret (RUSH-2443). Alias of `--private` on the CLI.
+     * unlisted, not secret (RUSH-2443). Alias of `--visibility unlisted` /
+     * `--private` on the CLI. Kept so `sessions share` and existing callers do
+     * not break.
      */
     unlisted?: boolean;
     /**
@@ -39,8 +47,12 @@ export interface PublishOptions {
     githubUser?: string;
     /** DI seam for tests — override the persisted share endpoint config. */
     config?: ShareConfig;
-    /** DI seam for tests — override the keychain-backed write token. */
+    /** DI seam for tests — override the keychain-backed write token. Selects BYO. */
     writeToken?: string;
+    /** DI seam for tests — override `readSession()`. `null` means signed out. */
+    session?: import('../identity/client.js').PhoenixSession | null;
+    /** Force the BYO Cloudflare path even when signed in. */
+    byo?: boolean;
     /** DI seam for tests — override the real HTTP PUT. */
     uploader?: PutFn;
     /** DI seam for tests — override cover capture (returns a PNG buffer or null). */
@@ -55,22 +67,26 @@ export interface PublishOptions {
     /**
      * Structured metadata (`--meta key=value`, repeatable). Keys are validated by
      * {@link parseMetaEntries} — lowercase `[a-z0-9-]`, and may not collide with
-     * {@link RESERVED_META_KEYS}, which the CLI sets automatically.
+     * {@link RESERVED_META_KEYS} (Worker-stamped owner/visibility/expires-at,
+     * plus provenance the CLI sets automatically).
      */
     meta?: Record<string, string>;
     /**
      * Skip revision retention on this publish — overwrite an existing slug's
      * object in place with no `<slug>/rev-<ts>` backup of the version it replaces
-     * (default: keep it; see docs/share.md §Revisions).
+     * (default: keep it; see docs/distribution.md).
      */
     noRevision?: boolean;
     /** DI seam for tests — override provenance auto-capture (agent/session/host/repo/date). */
     provenance?: ShareProvenance;
 }
+export type ShareVisibility = 'public' | 'unlisted';
 export interface PublishResult {
     url: string;
     expiresAt?: string;
     coverUrl?: string;
+    /** Server-enforced visibility stamped on the object. */
+    visibility?: ShareVisibility;
     /** True when the page was published with `visibility=unlisted`. */
     unlisted?: boolean;
     /** The label stored with this share — explicit (`--label`) or derived. */
@@ -78,6 +94,11 @@ export interface PublishResult {
     /** Whether `label` came from `--label` or was auto-derived. */
     labelSource?: 'explicit' | 'derived';
 }
+/** `--unlisted` / `{ unlisted: true }` map to `unlisted`; otherwise `visibility` (default public). */
+export declare function resolveShareVisibility(opts?: {
+    visibility?: ShareVisibility;
+    unlisted?: boolean;
+}): ShareVisibility;
 export interface ShareProvenance {
     /** Harness/agent name (`AGENTS_AGENT_NAME`), when publishing from an agent run. */
     agent?: string;
@@ -91,11 +112,12 @@ export interface ShareProvenance {
     date?: string;
 }
 /**
- * Reserved `customMetadata` keys the CLI sets automatically from the exec env,
- * git, and the local clock (plus `label`/`label-source`) — a `--meta key=value`
- * may not target any of these (see {@link parseMetaEntries}).
+ * Reserved `customMetadata` keys a `--meta key=value` may not target (see
+ * {@link parseMetaEntries}). Matches the Worker's `RESERVED_METADATA_KEYS`:
+ * provenance the CLI sets automatically, plus `expires-at` / `visibility` /
+ * `owner` which the Worker stamps itself.
  */
-export declare const RESERVED_META_KEYS: readonly ["agent", "session", "host", "repo", "date", "label", "label-source"];
+export declare const RESERVED_META_KEYS: readonly ["expires-at", "visibility", "owner", "agent", "session", "host", "repo", "date", "label", "label-source"];
 /**
  * Auto-capture publish provenance from the exec env, git, and the local clock.
  * Every field is present only when the environment genuinely carries it — a
@@ -113,8 +135,9 @@ export declare function resolveShareProvenance(opts?: {
 /**
  * Parse repeated `--meta key=value` CLI args into a validated metadata record.
  * Keys are lowercase `[a-z0-9-]`, up to 64 characters, and may not collide with
- * {@link RESERVED_META_KEYS} (the provenance the CLI sets automatically, plus
- * label/label-source) — throws naming the offending pair on any violation.
+ * {@link RESERVED_META_KEYS} (Worker-stamped owner/visibility/expires-at, plus
+ * the provenance the CLI sets automatically, plus label/label-source) — throws
+ * naming the offending pair on any violation.
  */
 export declare function parseMetaEntries(pairs: string[]): Record<string, string>;
 /** Throws when the combined `customMetadata` payload would exceed {@link MAX_METADATA_BYTES}. */
@@ -201,16 +224,17 @@ export declare function slugify(name: string): string;
 /** The project the file belongs to — git repo name, else the cwd's basename. */
 export declare function detectProject(dir?: string): string;
 /**
- * Notion-style default slug: `<project>-<feature>-<16hex>`. Project scopes the link
- * to the repo the agent is in; the random tail keeps it unguessable + collision-free.
- * A leading `plan-` on the filename is dropped (it's redundant under the project).
+ * Readable slug + view id: `<feature>-<16hex>`. A leading `plan-` on the
+ * filename is dropped. The project no longer prefixes the slug — the URL
+ * namespace is already the publisher's handle (`/<you>/<slug>`).
  *
  * The tail is 8 random bytes (64-bit, 16 hex chars). Reads are public — the URL is
  * the only capability — so the nonce must be genuinely infeasible to brute-force,
- * not merely unlisted; 64 bits puts a blind guess out of reach. (See docs/share.md
+ * not merely unlisted; 64 bits puts a blind guess out of reach. (See docs/distribution.md
  * §Security for the threat model and `--expire` for sensitive content.)
+ * `--slug` still publishes that exact slug, no view-id appended.
  */
-export declare function defaultSlug(filePath: string, dir?: string): string;
+export declare function defaultSlug(filePath: string, _dir?: string): string;
 /**
  * Best-effort OG cover: capture a screenshot, upload it as `<slug>.png`, and return
  * the page body with og:image meta injected (+ the cover URL). All IO is injected