pageship 0.4.1 → 0.5.0

package/dist/cli.mjs

@@ -683,6 +683,26 @@ const documentsUpdateVisibility = (options) => (options.client ?? client).patch(
 		...options.headers
 	}
 });
+const viewersList = (options) => (options.client ?? client).get({
+	url: "/api/v1/documents/{id}/viewers",
+	...options
+});
+const viewersAdd = (options) => (options.client ?? client).post({
+	url: "/api/v1/documents/{id}/viewers",
+	...options,
+	headers: {
+		"Content-Type": "application/json",
+		...options.headers
+	}
+});
+const viewersRemove = (options) => (options.client ?? client).delete({
+	url: "/api/v1/documents/{id}/viewers/{githubAccountId}",
+	...options
+});
+const githubGetUser = (options) => (options.client ?? client).get({
+	url: "/api/v1/github/users/{login}",
+	...options
+});
 //#endregion
 //#region ../../packages/api-client/src/generated/workspace-domain.gen.ts
 /** Every workspace address and document URL is a subdomain of this domain. */
@@ -760,14 +780,16 @@ function validTitle(value) {
 }
 function normalizeDocument(value) {
 	if (!record(value) || typeof value.slug !== "string") return;
-	const normalized = value.title === void 0 ? {
+	const normalized = {
 		...value,
-		title: value.slug
-	} : value;
+		...value.title === void 0 ? { title: value.slug } : {},
+		...value.viewCount === void 0 ? { viewCount: 0 } : {},
+		...value.sharedWith === void 0 ? { sharedWith: 0 } : {}
+	};
 	return validDocument(normalized) ? normalized : void 0;
 }
 function validDocument(value) {
-	return record(value) && isDocumentId(value.id) && typeof value.slug === "string" && /^[a-z0-9]+(?:-[a-z0-9]+)*(?![\s\S])/u.test(value.slug) && validTitle(value.title) && typeof value.sourcePath === "string" && value.sourcePath.length <= 1024 && /^(?!\/)(?!.*(?:^|\/)\.{1,2}(?:\/|$))(?!.*\/\/)[^\x00-\x1f\x7f\\:]*\.[hH][tT][mM][lL]?(?![\s\S])/u.test(value.sourcePath) && (value.repository === null || isRepository(value.repository)) && (value.visibility === "private" || value.visibility === "public") && isRevisionId(value.revisionId) && typeof value.byteLength === "number" && Number.isSafeInteger(value.byteLength) && value.byteLength > 0 && typeof value.createdAt === "number" && Number.isSafeInteger(value.createdAt) && value.createdAt >= 0 && typeof value.publishedAt === "number" && Number.isSafeInteger(value.publishedAt) && value.publishedAt >= 0 && typeof value.url === "string" && new RegExp(`^https://[a-z0-9-]+\\.${workspaceDomainPattern}/d/${value.id}-${value.slug}$`, "u").test(value.url);
+	return record(value) && isDocumentId(value.id) && typeof value.slug === "string" && /^[a-z0-9]+(?:-[a-z0-9]+)*(?![\s\S])/u.test(value.slug) && validTitle(value.title) && typeof value.sourcePath === "string" && value.sourcePath.length <= 1024 && /^(?!\/)(?!.*(?:^|\/)\.{1,2}(?:\/|$))(?!.*\/\/)[^\x00-\x1f\x7f\\:]*\.[hH][tT][mM][lL]?(?![\s\S])/u.test(value.sourcePath) && (value.repository === null || isRepository(value.repository)) && (value.visibility === "private" || value.visibility === "public") && isRevisionId(value.revisionId) && typeof value.byteLength === "number" && Number.isSafeInteger(value.byteLength) && value.byteLength > 0 && typeof value.createdAt === "number" && Number.isSafeInteger(value.createdAt) && value.createdAt >= 0 && typeof value.publishedAt === "number" && Number.isSafeInteger(value.publishedAt) && value.publishedAt >= 0 && typeof value.viewCount === "number" && Number.isSafeInteger(value.viewCount) && value.viewCount >= 0 && typeof value.sharedWith === "number" && Number.isSafeInteger(value.sharedWith) && value.sharedWith >= 0 && typeof value.url === "string" && new RegExp(`^https://[a-z0-9-]+\\.${workspaceDomainPattern}/d/${value.id}-${value.slug}$`, "u").test(value.url);
 }
 function validRevision(value, documentId) {
 	return record(value) && isRevisionId(value.id) && typeof value.createdAt === "number" && Number.isSafeInteger(value.createdAt) && value.createdAt >= 0 && typeof value.byteLength === "number" && Number.isSafeInteger(value.byteLength) && value.byteLength > 0 && typeof value.isCurrent === "boolean" && (value.cliVersion === null || isCliVersion(value.cliVersion)) && typeof value.url === "string" && new RegExp(`^https://[a-z0-9-]+\\.${workspaceDomainPattern}/d/${documentId}-[a-z0-9]+(?:-[a-z0-9]+)*/revisions/${value.id}$`, "u").test(value.url);
@@ -913,9 +935,12 @@ async function updateDocumentVisibility(baseUrl, id, visibility, options = {}) {
 		throw new Error("Could not update document visibility. Try again.", { cause: error });
 	}
 	const data = received;
-	if (record(data) && data.status === "visibility_updated" && validDocument(data.document) && data.document.visibility === visibility) return {
+	const updated = record(data) && data.status === "visibility_updated" ? normalizeDocument(data.document) : void 0;
+	const removedViewers = record(data) && data.removedViewers !== void 0 ? data.removedViewers : 0;
+	if (updated?.visibility === visibility && typeof removedViewers === "number" && Number.isSafeInteger(removedViewers) && removedViewers >= 0) return {
 		status: "visibility_updated",
-		document: data.document
+		document: updated,
+		removedViewers
 	};
 	throw new Error("Invalid document visibility response.");
 }
@@ -957,6 +982,92 @@ async function publishDocument(baseUrl, input, options = {}) {
 	if (record(data) && (data.status === "idempotency_conflict" || data.status === "address_required" || data.status === "unavailable" || data.status === "document_id_taken")) return { status: data.status };
 	throw new Error("Invalid publication response. Retry with the same idempotency key.");
 }
+/** Same GitHub username grammar as the Effect contract. */
+function isGitHubLogin(value) {
+	return typeof value === "string" && /^[A-Za-z0-9][A-Za-z0-9-]{0,38}(?![\s\S])/u.test(value);
+}
+function isGitHubAccountId(value) {
+	return typeof value === "string" && /^[1-9][0-9]{0,19}(?![\s\S])/u.test(value);
+}
+function validViewer(value) {
+	return record(value) && isGitHubAccountId(value.githubAccountId) && isGitHubLogin(value.login) && (value.name === null || typeof value.name === "string") && typeof value.addedAt === "number" && Number.isSafeInteger(value.addedAt) && value.addedAt >= 0;
+}
+function validUserMatch(value) {
+	return record(value) && isGitHubAccountId(value.githubAccountId) && isGitHubLogin(value.login);
+}
+function validUserProfile(value) {
+	return record(value) && (value.name === null || typeof value.name === "string") && (value.type === "user" || value.type === "organization" || value.type === "other") && validUserMatch(value);
+}
+/**
+* One message per viewer refusal. The body's status picks it, not the HTTP code: a refused
+* GitHub token and a signed-out session are both 401.
+*/
+const viewerRefusals = {
+	signed_out: "Sign in to manage viewers.",
+	uninvited: "Access unavailable.",
+	forbidden: "A trusted browser origin is required.",
+	unavailable: "Document unavailable.",
+	document_public: "Make the document private before adding viewers.",
+	github_user_not_found: "GitHub has no user with that username.",
+	github_account_mismatch: "That username now belongs to a different GitHub account. Look it up again.",
+	not_personal_account: "Only a personal GitHub account can be a viewer.",
+	owner_account: "You already have access to your own document.",
+	github_sign_in_required: "GitHub refused your sign-in. Sign in to Pageship again.",
+	github_rate_limited: "GitHub is limiting requests. Try again in a minute.",
+	github_unavailable: "GitHub is unavailable. Try again."
+};
+function isViewerRefusal(value) {
+	return typeof value === "string" && Object.hasOwn(viewerRefusals, value);
+}
+function viewerFailed(response, error) {
+	if (response && record(error) && isViewerRefusal(error.status)) throw new DocumentRequestError(error.status, viewerRefusals[error.status], response.status);
+	failed(response, error);
+}
+async function getDocumentViewers(baseUrl, id, options = {}) {
+	const { data, response, error } = await viewersList({
+		...requestOptions(baseUrl, options),
+		path: { id }
+	});
+	if (!response?.ok) viewerFailed(response, error);
+	if (data?.status === "listed" && Array.isArray(data.viewers) && data.viewers.every(validViewer)) return data;
+	throw new Error("Invalid document viewer listing response.");
+}
+/** Adds the account the owner confirmed. The server looks the login up again before adding it. */
+async function addDocumentViewer(baseUrl, id, user, options = {}) {
+	const { data, response, error } = await viewersAdd({
+		...changeOptions(baseUrl, options),
+		path: { id },
+		body: {
+			githubAccountId: user.githubAccountId,
+			login: user.login
+		}
+	});
+	if (!response?.ok) viewerFailed(response, error);
+	if (data?.status === "added" && validViewer(data.viewer) && data.viewer.githubAccountId === user.githubAccountId) return data;
+	throw new Error("Invalid document viewer response.");
+}
+/** Removing an account that isn't a viewer succeeds. */
+async function removeDocumentViewer(baseUrl, id, githubAccountId, options = {}) {
+	const { data, response, error } = await viewersRemove({
+		...changeOptions(baseUrl, options),
+		path: {
+			id,
+			githubAccountId
+		}
+	});
+	if (!response?.ok) viewerFailed(response, error);
+	if (data?.status === "removed") return { status: "removed" };
+	throw new Error("Invalid document viewer removal response.");
+}
+async function getGitHubUser(baseUrl, login, options = {}) {
+	const { data, response, error } = await githubGetUser({
+		...requestOptions(baseUrl, options),
+		path: { login }
+	});
+	if (!response?.ok) viewerFailed(response, error);
+	if (data?.status === "found" && validUserProfile(data.user)) return data;
+	throw new Error("Invalid GitHub user response.");
+}
 //#endregion
 //#region ../../packages/api-client/src/index.ts
 async function getWorkspace(baseUrl, options = {}) {
@@ -971,7 +1082,17 @@ async function getWorkspace(baseUrl, options = {}) {
 		throwOnError: false
 	});
 	if (!response?.ok) throw new Error("Could not load your workspace.", { cause: error });
-	if (data?.status === "signed_out" || data?.status === "uninvited") return { status: data.status };
+	if (data?.status === "signed_out") return { status: data.status };
+	if (data?.status === "uninvited") {
+		const user = data.user;
+		return user && typeof user.name === "string" && (user.login === void 0 || typeof user.login === "string") ? {
+			status: data.status,
+			user: {
+				name: user.name,
+				...user.login ? { login: user.login } : {}
+			}
+		} : { status: data.status };
+	}
 	if (data?.status === "admitted" && typeof data.user?.id === "string" && data.user.id.length > 0 && typeof data.user?.name === "string" && (data.user.login === void 0 || typeof data.user.login === "string") && (data.user.githubAccountId === void 0 || typeof data.user.githubAccountId === "string" && /^[1-9]\d*$/u.test(data.user.githubAccountId)) && typeof data.workspace?.id === "string" && data.workspace.id.length > 0 && (data.address === void 0 || data.address === null || isWorkspaceAddress(data.address))) return data;
 	throw new Error("Invalid workspace response.");
 }
@@ -1325,6 +1446,7 @@ const outcomes = {
 	downloaded: "succeeded",
 	visibility_updated: "succeeded",
 	restored: "succeeded",
+	viewers_updated: "succeeded",
 	skills_installed: "succeeded",
 	authorization_pending: "pending",
 	expired: "pending",
@@ -1336,6 +1458,7 @@ const outcomes = {
 	repository_mismatch: "pending",
 	marker_unavailable: "pending",
 	revision_conflict: "pending",
+	github_sign_in_required: "pending",
 	cancelled: "pending",
 	usage_error: "failed",
 	internal_error: "failed",
@@ -1359,7 +1482,15 @@ const outcomes = {
 	idempotency_conflict: "failed",
 	document_id_taken: "failed",
 	publication_action_unsupported: "failed",
-	skills_modified: "failed"
+	skills_modified: "failed",
+	ambiguous_viewer: "failed",
+	document_public: "failed",
+	github_user_not_found: "failed",
+	github_account_mismatch: "failed",
+	not_personal_account: "failed",
+	owner_account: "failed",
+	github_rate_limited: "failed",
+	github_unavailable: "failed"
 };
 const isStatus = (value) => Object.hasOwn(outcomes, value);
 const commandNames = [
@@ -1371,6 +1502,7 @@ const commandNames = [
 	"history",
 	"download",
 	"visibility",
+	"viewers",
 	"restore",
 	"skills"
 ];
@@ -1422,7 +1554,7 @@ function commandLine(command, args) {
 }
 //#endregion
 //#region package.json
-var version = "0.4.1";
+var version = "0.5.0";
 //#endregion
 //#region src/publish.ts
 const execute = promisify(execFile);
@@ -2142,6 +2274,25 @@ async function identify(serverValue, signal) {
 }
 //#endregion
 //#region src/documents.ts
+/** `1 viewer`, `2 viewers`. */
+const viewerCount = (count) => `${count} viewer${count === 1 ? "" : "s"}`;
+/** The result for a request the server refused. `login` signs in again. */
+function refusal(error, login) {
+	const status = error.status;
+	if (status === "signed_out") return {
+		status,
+		message: `Your credential was revoked, expired or is invalid. Run ${commandLine(login.command, login.args)} to sign in again.`,
+		next: login
+	};
+	if (status === "uninvited") return {
+		status,
+		message: "This account is not invited. Contact the server owner."
+	};
+	return {
+		status,
+		message: error.message
+	};
+}
 /** Checks compatibility and the stored credential; the server enforces ownership and admission. */
 async function asOwner(serverValue, signal, operation) {
 	const selection = selectServer(serverValue);
@@ -2174,14 +2325,11 @@ async function asOwner(serverValue, signal, operation) {
 			signal
 		});
 	} catch (error) {
-		if (!(error instanceof DocumentRequestError && isStatus(error.status))) throw error;
-		return {
-			status: error.status,
-			message: error.status === "signed_out" ? `Your credential was revoked, expired or is invalid. Run ${login} to sign in again.` : error.status === "uninvited" ? "This account is not invited. Contact the server owner." : error.message,
-			...error.status === "signed_out" ? { next } : {}
-		};
+		if (!isRefusal(error)) throw error;
+		return refusal(error, next);
 	}
 }
+const isRefusal = (error) => error instanceof DocumentRequestError && isStatus(error.status);
 function listDocuments(options) {
 	return asOwner(options.server, options.signal, async ({ origin, args }, request) => {
 		const page = await getDocuments(origin, {
@@ -2201,7 +2349,7 @@ function listDocuments(options) {
 			...next ? { next } : {},
 			message: [
 				page.documents.length ? "Documents:" : options.cursor ? "No more documents." : "No documents.",
-				...page.documents.map((document) => `${document.id}  ${document.visibility}  ${document.title}\n` + (document.repository ? `  repository ${document.repository}\n` : "") + `  source ${document.sourcePath}\n  current revision ${document.revisionId}\n  ${document.url}`),
+				...page.documents.map((document) => `${document.id}  ${document.visibility}  ${viewerCount(document.sharedWith)}  ${document.title}\n` + (document.repository ? `  repository ${document.repository}\n` : "") + `  source ${document.sourcePath}\n  current revision ${document.revisionId}\n  ${document.url}`),
 				...next ? [`More documents: run ${commandLine(next.command, next.args)}`] : []
 			].join("\n")
 		};
@@ -2280,9 +2428,10 @@ function downloadDocument(options) {
 function changeVisibility(options) {
 	return asOwner(options.server, options.signal, async ({ origin }, request) => {
 		const result = await updateDocumentVisibility(origin, options.documentId, options.visibility, request);
+		const { document, removedViewers } = result;
 		return {
 			...result,
-			message: result.document.visibility === "public" ? `${result.document.id} is public. Anyone with the URL can read its current revision: ${result.document.url}` : `${result.document.id} is private. Only you can read it after signing in: ${result.document.url}`
+			message: document.visibility === "public" ? `${document.id} is public.${removedViewers ? ` Removed its ${viewerCount(removedViewers)}.` : ""} Anyone with the URL can read its current revision: ${document.url}` : `${document.id} is private. Only you and its ${document.sharedWith ? viewerCount(document.sharedWith) : "viewers"} can read it after signing in: ${document.url}`
 		};
 	});
 }
@@ -2752,6 +2901,132 @@ async function checkReadiness(serverValue, signal) {
 	};
 }
 //#endregion
+//#region src/viewers.ts
+/** `octocat (Mona Lisa), GitHub ID 583231` */
+const account = ({ login, name, githubAccountId }) => `${login}${name ? ` (${name})` : ""}, GitHub ID ${githubAccountId}`;
+function viewerList(documentId, viewers) {
+	return viewers.length ? [`Viewers of ${documentId}:`, ...viewers.map((viewer) => `  ${account(viewer)}`)].join("\n") : `${documentId} has no viewers.`;
+}
+/**
+* Lists a document's viewers, or changes them. Every removal is matched and every added username
+* looked up before anything changes. Removals run first, then additions.
+*/
+function manageViewers(options) {
+	const { documentId, add, remove } = options;
+	return asOwner(options.server, options.signal, async ({ origin, args }, request) => {
+		const login = {
+			command: "login",
+			args
+		};
+		const next = {
+			command: "viewers",
+			args: [
+				documentId,
+				...args,
+				...remove.flatMap((value) => ["--remove", value]),
+				...add.flatMap((value) => ["--add", value])
+			]
+		};
+		const progress = [];
+		const added = [];
+		const removed = [];
+		const changed = () => added.length || removed.length ? {
+			added,
+			removed
+		} : {};
+		try {
+			const { viewers } = await getDocumentViewers(origin, documentId, request);
+			if (!add.length && !remove.length) return {
+				status: "listed",
+				documentId,
+				viewers,
+				message: viewerList(documentId, viewers)
+			};
+			const removals = [];
+			const notViewers = [];
+			for (const value of remove) {
+				const matches = /^[0-9]+$/u.test(value) ? viewers.filter((viewer) => viewer.githubAccountId === value) : viewers.filter((viewer) => viewer.login.toLowerCase() === value.toLowerCase());
+				if (matches.length > 1) return {
+					status: "ambiguous_viewer",
+					documentId,
+					value,
+					matches,
+					message: [`${value} matches ${matches.length} viewers of ${documentId}. Nothing was changed. Remove one by its GitHub ID with --remove <id>:`, ...matches.map((viewer) => `  ${account(viewer)}`)].join("\n")
+				};
+				if (!matches[0]) notViewers.push(value);
+				else if (!removals.includes(matches[0])) removals.push(matches[0]);
+			}
+			const accounts = [];
+			for (const value of add) {
+				const { user } = await getGitHubUser(origin, value, request);
+				if (user.type !== "user") return {
+					status: "not_personal_account",
+					documentId,
+					user,
+					message: `${account(user)} is ${user.type === "organization" ? "an organization" : "not a personal account"}. Only a personal GitHub account can be a viewer. Nothing was changed.`
+				};
+				progress.push(`Found ${account(user)}.`);
+				if (!accounts.some(({ githubAccountId }) => githubAccountId === user.githubAccountId)) accounts.push(user);
+			}
+			for (const viewer of removals) {
+				await removeDocumentViewer(origin, documentId, viewer.githubAccountId, request);
+				removed.push(viewer);
+				progress.push(`Removed ${account(viewer)}.`);
+			}
+			for (const user of accounts) {
+				const { viewer } = await addDocumentViewer(origin, documentId, user, request);
+				added.push(viewer);
+				progress.push(`Added ${account(viewer)}.`);
+			}
+			const current = await getDocumentViewers(origin, documentId, request);
+			return {
+				status: "viewers_updated",
+				documentId,
+				added,
+				removed,
+				notViewers,
+				viewers: current.viewers,
+				message: [
+					...progress,
+					...notViewers.map((value) => `${value} is not a viewer of ${documentId}.`),
+					viewerList(documentId, current.viewers)
+				].join("\n")
+			};
+		} catch (error) {
+			const prefix = (result) => ({
+				...result,
+				documentId,
+				...changed(),
+				message: [...progress, result.message].join("\n")
+			});
+			if (isRefusal(error)) {
+				const { status } = error;
+				if (status === "github_sign_in_required") return prefix({
+					status,
+					message: `GitHub refused the sign-in Pageship uses to look up GitHub users. Sign in to the Pageship dashboard again with GitHub, then run ${commandLine(next.command, next.args)}.`,
+					next
+				});
+				if (status === "github_rate_limited" || status === "github_unavailable") return prefix({
+					status,
+					message: error.message,
+					next
+				});
+				return prefix(refusal(error, login));
+			}
+			if (!added.length && !removed.length) throw error;
+			return prefix(options.signal.aborted ? {
+				status: "interrupted",
+				message: `Operation interrupted. Run ${commandLine(next.command, next.args)} to finish.`,
+				next
+			} : {
+				status: "request_failed",
+				message: `${error instanceof Error ? error.message : String(error)} Run ${commandLine(next.command, next.args)} to finish.`,
+				next
+			});
+		}
+	});
+}
+//#endregion
 //#region src/cli.ts
 const args = process.argv.slice(2);
 const separator = args.indexOf("--");
@@ -2905,6 +3180,18 @@ const visibility = Command.make("visibility", {
 	visibility,
 	signal
 }))).pipe(Command.withDescription("Make a document private or public."));
+const viewers = Command.make("viewers", {
+	documentId: documentIdArgument,
+	add: Flag.string("add").pipe(Flag.filter((value) => isGitHubLogin(value), () => "Use a GitHub username."), Flag.withDescription("Look up this GitHub username and add the account it names as a viewer. Repeat to add several."), Flag.atLeast(0)),
+	remove: Flag.string("remove").pipe(Flag.filter((value) => isGitHubLogin(value), () => "Use a viewer's GitHub username or GitHub ID."), Flag.withDescription("Remove the viewer with this GitHub username or GitHub ID. Repeat to remove several."), Flag.atLeast(0)),
+	server: serverFlag
+}, ({ documentId, add, remove, server }) => authCommand("viewers", (signal) => manageViewers({
+	server: Option.getOrUndefined(server),
+	documentId,
+	add,
+	remove,
+	signal
+}))).pipe(Command.withDescription("List the GitHub users who can read a private document, or add and remove them."));
 const restore = Command.make("restore", {
 	documentId: documentIdArgument,
 	server: serverFlag,
@@ -2977,7 +3264,7 @@ function authCommand(name, operation) {
 		}
 	});
 }
-const command = Command.make("pageship").pipe(Command.withDescription("Pageship publishes private HTML documents on the hosted Pageship service.\n\nEarly development: check whether this installation is ready with the status command. Authorize this installation with login, then publish one HTML file with publish. Manage published documents with list, history, download, visibility and restore. Install the Pageship skills for your agents with skills install."), Command.withSubcommands([
+const command = Command.make("pageship").pipe(Command.withDescription("Pageship publishes private HTML documents on the hosted Pageship service.\n\nEarly development: check whether this installation is ready with the status command. Authorize this installation with login, then publish one HTML file with publish. Manage published documents with list, history, download, visibility, viewers and restore. Install the Pageship skills for your agents with skills install."), Command.withSubcommands([
 	status,
 	login,
 	whoami,
@@ -2986,6 +3273,7 @@ const command = Command.make("pageship").pipe(Command.withDescription("Pageship
 	history,
 	download,
 	visibility,
+	viewers,
 	restore,
 	skills
 ]), Command.withGlobalFlags([jsonFlag]));

package/dist/skills/pageship/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: pageship
-description: Publish an HTML file to Pageship and manage what is published. Use when the user asks to publish, share or get a link to a document, update its published copy, change its visibility, list, inspect history, download or restore published documents, or sign in to Pageship. To write, edit, rename or move a document, load pageship-docs instead.
+description: Publish an HTML file to Pageship and manage what is published. Use when the user asks to publish, share or get a link to a document, update its published copy, change its visibility or viewers, list, inspect history, download or restore published documents, or sign in to Pageship. To write, edit, rename or move a document, load pageship-docs instead.
 license: MIT
 metadata:
-  version: "0.4.1"
+  version: "0.5.0"
 ---
 
 # Pageship
@@ -97,7 +97,7 @@ After a successful upload the CLI adds the document marker to the end of the loc
 On `published`, tell the user:
 
 - the document URL, `document.url`;
-- who can read it, from `document.visibility`: a private document opens only for its owner, signed in;
+- who can read it, from `document.visibility`: a private document opens only for its owner and its viewers, signed in;
 - whether this publish created a new document or revised an existing one, from `change`: `created` or `revised`.
 
 Keep `idempotencyKey` only while you resolve an uncertain attempt.
@@ -124,7 +124,11 @@ This works for any document the user owns, even when the file moved or belongs t
 
 ## Share a document
 
-A request to share a document, or to send someone its link, is a request to publish it. Publish it as above and report the publish. A new document is private. When the result is private, ask whether to make it public, and say in the question that anyone with the link can then read it. When it is already public, because the user made it public earlier, say so and don't ask. Change visibility only after the user agrees, as in [visibility](references/visibility.md).
+A request to share a document, or to send someone its link, is a request to publish it. Publish it as above and report the publish. A new document is private.
+
+When the user names the people to share it with, keep it private and add them as viewers, as in [viewers](references/viewers.md). Sharing with named people never makes a document public.
+
+When the user names no one and the result is private, ask whether to make it public, and say in the question that anyone with the link can then read it. Mention that it can instead stay private and be shared with named GitHub users. When it is already public, because the user made it public earlier, say so and don't ask. Change visibility only after the user agrees, as in [visibility](references/visibility.md).
 
 ## Use another server
 
@@ -137,6 +141,7 @@ Load the reference for the task:
 - [List and history](references/list-and-history.md): find a document's `id`, `visibility`, current `revisionId` and `url`, and inspect its revisions.
 - [Download](references/download.md): read a document's HTML, current or from an earlier revision.
 - [Visibility](references/visibility.md): make a document public or private.
+- [Viewers](references/viewers.md): list, add or remove the GitHub users who can read a private document.
 - [Restore](references/restore.md): make an earlier revision current again.
 
 Deleting a document, recovering a deleted one, changing a document's display title and revoking a CLI installation happen in the dashboard, at https://app.pageship.dev for the hosted service. The CLI has no commands for them yet, so give the user the dashboard link.

package/dist/skills/pageship/references/viewers.md

@@ -0,0 +1,43 @@
+# Viewers
+
+A viewer is a GitHub user who can read a private document after signing in with GitHub. The owner always can. Viewers see only the current revision, never the history.
+
+## Share with named people
+
+Add viewers only for people the user named in this conversation. When the user names a person without a GitHub username, ask for it; a GitHub username is the only way to name a viewer. Sharing with people keeps the document private: a request to share a document with someone is never a request to make it public. A public document can't have viewers, so if it is public, ask the user whether to make it private first, as in [visibility](visibility.md), and add no one until they agree.
+
+Set `PAGESHIP_DOCUMENT` to the document's `id`, then add each named username with its own `--add`:
+
+```sh
+pageship --json viewers "$PAGESHIP_DOCUMENT" --add octocat --add hubot
+```
+
+The CLI looks each username up on GitHub before it changes anything. `added` holds each account it added, with `login`, `name` and `githubAccountId`, on `viewers_updated` and on a failure partway through. Whatever the status, show the user every account in `added` by `login` and `name`, and ask them to confirm each is the person they meant. A username can belong to someone else. If one is wrong, remove it as below. Then give the user the document's `url` to send: Pageship sends no invitations.
+
+## List and remove viewers
+
+To see who can read the document, run:
+
+```sh
+pageship --json viewers "$PAGESHIP_DOCUMENT"
+```
+
+On `listed`, `viewers` holds each viewer's `login`, `name` and `githubAccountId`. A viewer's `login` is the one they had when added or last signed in, so two viewers can show the same `login`.
+
+Remove viewers only when the user asks. Pass a `login` or a `githubAccountId`, one `--remove` each. A value of only digits is always a `githubAccountId`, so remove a viewer whose `login` is all digits by its `githubAccountId`:
+
+```sh
+pageship --json viewers "$PAGESHIP_DOCUMENT" --remove octocat
+```
+
+`notViewers` names values that matched no viewer; nothing was needed for them. On `ambiguous_viewer`, the value matched more than one viewer and nothing changed. Show the user `matches` and ask which one, then remove it by its `githubAccountId`.
+
+## Outcomes
+
+- `github_user_not_found`, `not_personal_account` or `owner_account`: nothing changed for that username. Report the `message` and ask the user for the right GitHub username. Only a personal account can be a viewer, and the owner can always read their own document.
+- `github_account_mismatch`: the username moved to another account between the lookup and the change. Report the `message` and ask the user to confirm the username before you run the same command again.
+- `document_public`: the document is public. Ask whether to make it private before adding anyone.
+- `github_sign_in_required`: GitHub refused the sign-in Pageship uses to look up users. Ask the user to sign in to the Pageship dashboard again with GitHub, then run the returned `next`. A CLI `login` doesn't fix this.
+- `github_rate_limited` or `github_unavailable`: wait a minute, then run the returned `next`.
+
+A failure partway through keeps the changes already made, listed in `added` and `removed`. Its `next` repeats the command, which finishes the rest without adding or removing anyone twice.

package/dist/skills/pageship/references/visibility.md

@@ -1,6 +1,6 @@
 # Visibility
 
-A private document opens only for its owner, signed in. Anyone with the link can read a public one, without signing in.
+A private document opens only for its owner and its [viewers](viewers.md), signed in. Anyone with the link can read a public one, without signing in. Making a document public removes all its viewers.
 
 Change visibility only when the user asked for a policy by name, such as "make it public", or agreed when you asked after sharing. Set `PAGESHIP_DOCUMENT` to the document's `id`, then run one of:
 
@@ -9,4 +9,4 @@ pageship --json visibility "$PAGESHIP_DOCUMENT" public
 pageship --json visibility "$PAGESHIP_DOCUMENT" private
 ```
 
-On `visibility_updated`, report the returned `document.visibility` and `document.url`. Publishing a new revision keeps the document's visibility.
+On `visibility_updated`, report the returned `document.visibility` and `document.url`, and `removedViewers` when it is more than 0. Publishing a new revision keeps the document's visibility.

package/dist/skills/pageship-chart/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: pageship-chart
-description: Later step of pageship-docs: for a request to write or edit a document, load pageship-docs first; load this skill first only when the user names it. Pattern for charts in a Pageship HTML document, loaded by a pageship- kind skill before it draws a chart.
+description: "Later step of pageship-docs: for a request to write or edit a document, load pageship-docs first; load this skill first only when the user names it. Pattern for charts in a Pageship HTML document, loaded by a pageship- kind skill before it draws a chart."
 license: MIT
 metadata:
-  version: "0.4.1"
+  version: "0.5.0"
 ---
 
 # Chart

package/dist/skills/pageship-code-block/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: pageship-code-block
-description: Later step of pageship-docs: for a request to write or edit a document, load pageship-docs first; load this skill first only when the user names it. Pattern for code in a Pageship HTML document, such as source code, commands, configuration or logs, loaded by a pageship- kind skill before the first code block.
+description: "Later step of pageship-docs: for a request to write or edit a document, load pageship-docs first; load this skill first only when the user names it. Pattern for code in a Pageship HTML document, such as source code, commands, configuration or logs, loaded by a pageship- kind skill before the first code block."
 license: MIT
 metadata:
-  version: "0.4.1"
+  version: "0.5.0"
 ---
 
 # Code block

package/dist/skills/pageship-decision-record/SKILL.md

@@ -3,7 +3,7 @@ name: pageship-decision-record
 description: HTML decision records, as the second step of pageship-docs. For any request to record, write, regenerate, edit or move a decision, load pageship-docs first; load this skill first only when the user names it.
 license: MIT
 metadata:
-  version: "0.4.1"
+  version: "0.5.0"
 ---
 
 # Decision record

package/dist/skills/pageship-diagram/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: pageship-diagram
-description: Later step of pageship-docs: for a request to write or edit a document, load pageship-docs first; load this skill first only when the user names it. Pattern for diagrams in a Pageship HTML document, such as a process, a timeline, a system map or states, loaded by a pageship- kind skill before it draws a diagram.
+description: "Later step of pageship-docs: for a request to write or edit a document, load pageship-docs first; load this skill first only when the user names it. Pattern for diagrams in a Pageship HTML document, such as a process, a timeline, a system map or states, loaded by a pageship- kind skill before it draws a diagram."
 license: MIT
 metadata:
-  version: "0.4.1"
+  version: "0.5.0"
 ---
 
 # Diagram

package/dist/skills/pageship-docs/SKILL.md

@@ -3,7 +3,7 @@ name: pageship-docs
 description: First step for any document people read, such as a report, plan, spec, explainer, review, decision record or slide deck, in HTML or Markdown. Load it before any other pageship- skill. Use when the user asks for one of these documents, asks to regenerate, redesign, edit, rename, move or copy an HTML source file, or asks to record whether they want HTML or Markdown.
 license: MIT
 metadata:
-  version: "0.4.1"
+  version: "0.5.0"
 ---
 
 # Pageship documents

package/dist/skills/pageship-explainer/SKILL.md

@@ -3,7 +3,7 @@ name: pageship-explainer
 description: HTML explainers, as the second step of pageship-docs. For any request to explain how something works, or to write, regenerate, edit or move an explainer, load pageship-docs first; load this skill first only when the user names it.
 license: MIT
 metadata:
-  version: "0.4.1"
+  version: "0.5.0"
 ---
 
 # Explainer

package/dist/skills/pageship-interaction/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: pageship-interaction
-description: Later step of pageship-docs: for a request to write or edit a document, load pageship-docs first; load this skill first only when the user names it. Pattern for controls in a Pageship HTML document, such as stepping through stages, tracing a path, tabs, filters, revealing detail and pointer states on charts and diagrams, loaded by a pageship- kind skill before it adds any control.
+description: "Later step of pageship-docs: for a request to write or edit a document, load pageship-docs first; load this skill first only when the user names it. Pattern for controls in a Pageship HTML document, such as stepping through stages, tracing a path, tabs, filters, revealing detail and pointer states on charts and diagrams, loaded by a pageship- kind skill before it adds any control."
 license: MIT
 metadata:
-  version: "0.4.1"
+  version: "0.5.0"
 ---
 
 # Interaction

package/dist/skills/pageship-key-figures/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: pageship-key-figures
-description: Later step of pageship-docs: for a request to write or edit a document, load pageship-docs first; load this skill first only when the user names it. Pattern for the few numbers and callouts a Pageship HTML document opens with, loaded by a pageship- kind skill before it writes key figures.
+description: "Later step of pageship-docs: for a request to write or edit a document, load pageship-docs first; load this skill first only when the user names it. Pattern for the few numbers and callouts a Pageship HTML document opens with, loaded by a pageship- kind skill before it writes key figures."
 license: MIT
 metadata:
-  version: "0.4.1"
+  version: "0.5.0"
 ---
 
 # Key figures

package/dist/skills/pageship-media/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: pageship-media
-description: Later step of pageship-docs: for a request to write or edit a document, load pageship-docs first; load this skill first only when the user names it. Pattern for images, video and audio in a Pageship HTML document, loaded by a pageship- kind skill before it shows media.
+description: "Later step of pageship-docs: for a request to write or edit a document, load pageship-docs first; load this skill first only when the user names it. Pattern for images, video and audio in a Pageship HTML document, loaded by a pageship- kind skill before it shows media."
 license: MIT
 metadata:
-  version: "0.4.1"
+  version: "0.5.0"
 ---
 
 # Media

package/dist/skills/pageship-motion/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: pageship-motion
-description: Later step of pageship-docs: for a request to write or edit a document, load pageship-docs first; load this skill first only when the user names it. Pattern for animation and transitions in a Pageship HTML document, such as a chart that grows into view, a sequence that plays through a diagram, or a marker moving along a path, loaded by a pageship- kind skill before it draws a chart, a graphic or a sequence, or before anything else on the page moves.
+description: "Later step of pageship-docs: for a request to write or edit a document, load pageship-docs first; load this skill first only when the user names it. Pattern for animation and transitions in a Pageship HTML document, such as a chart that grows into view, a sequence that plays through a diagram, or a marker moving along a path, loaded by a pageship- kind skill before it draws a chart, a graphic or a sequence, or before anything else on the page moves."
 license: MIT
 metadata:
-  version: "0.4.1"
+  version: "0.5.0"
 ---
 
 # Motion

package/dist/skills/pageship-plan/SKILL.md

@@ -3,7 +3,7 @@ name: pageship-plan
 description: HTML plans, as the second step of pageship-docs. For any request to write, regenerate, edit or move a plan, load pageship-docs first; load this skill first only when the user names it.
 license: MIT
 metadata:
-  version: "0.4.1"
+  version: "0.5.0"
 ---
 
 # Plan

package/dist/skills/pageship-report/SKILL.md

@@ -3,7 +3,7 @@ name: pageship-report
 description: HTML reports, as the second step of pageship-docs. For any request to write, regenerate, edit or move a report, load pageship-docs first; load this skill first only when the user names it.
 license: MIT
 metadata:
-  version: "0.4.1"
+  version: "0.5.0"
 ---
 
 # Report

package/dist/skills/pageship-review-report/SKILL.md

@@ -3,7 +3,7 @@ name: pageship-review-report
 description: HTML review reports, as the second step of pageship-docs. For any request to review a change or a plan and write up the findings, or to write, regenerate, edit or move a review report, load pageship-docs first; load this skill first only when the user names it.
 license: MIT
 metadata:
-  version: "0.4.1"
+  version: "0.5.0"
 ---
 
 # Review report

package/dist/skills/pageship-slide-deck/SKILL.md

@@ -3,7 +3,7 @@ name: pageship-slide-deck
 description: HTML slide decks, as the second step of pageship-docs. For any request to make slides or a presentation, or to regenerate, edit or move a deck, load pageship-docs first; load this skill first only when the user names it.
 license: MIT
 metadata:
-  version: "0.4.1"
+  version: "0.5.0"
 ---
 
 # Slide deck

package/dist/skills/pageship-spec/SKILL.md

@@ -3,7 +3,7 @@ name: pageship-spec
 description: HTML specs, as the second step of pageship-docs. For any request to write, regenerate, edit or move a spec, load pageship-docs first; load this skill first only when the user names it.
 license: MIT
 metadata:
-  version: "0.4.1"
+  version: "0.5.0"
 ---
 
 # Spec

package/dist/skills/pageship-table/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: pageship-table
-description: Later step of pageship-docs: for a request to write or edit a document, load pageship-docs first; load this skill first only when the user names it. Pattern for tables in a Pageship HTML document, loaded by a pageship- kind skill before it writes a table.
+description: "Later step of pageship-docs: for a request to write or edit a document, load pageship-docs first; load this skill first only when the user names it. Pattern for tables in a Pageship HTML document, loaded by a pageship- kind skill before it writes a table."
 license: MIT
 metadata:
-  version: "0.4.1"
+  version: "0.5.0"
 ---
 
 # Table

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pageship",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "Pageship CLI for checking server API compatibility.",
   "license": "UNLICENSED",
   "repository": {