pageship 0.6.1 → 0.7.0

package/README.md

@@ -1,6 +1,6 @@
 # Pageship CLI
 
-Pageship is an HTML publishing service in development. This CLI signs you in to the hosted Pageship service through a browser, publishes HTML files as documents behind stable links, and lists, downloads, restores and changes the visibility of the documents you published. It also installs the Pageship skills for your agents.
+Pageship is an HTML publishing service in development. This CLI signs you in to the hosted Pageship service through a browser, publishes HTML files as documents behind stable links, and lists, downloads, restores and changes the visibility of the documents you published. It also reads documents other people shared with you, by their links. It also installs the Pageship skills for your agents.
 
 The full reference, with every command, option and result, is at https://pageship.dev/docs/cli.
 

package/dist/cli.mjs

@@ -675,6 +675,18 @@ const documentsRestore = (options) => (options.client ?? client).post({
 		...options.headers
 	}
 });
+const installationsList = (options) => (options?.client ?? client).get({
+	url: "/api/v1/installations",
+	...options
+});
+const installationsRevoke = (options) => (options.client ?? client).post({
+	url: "/api/v1/installations/revoke",
+	...options,
+	headers: {
+		"Content-Type": "application/json",
+		...options.headers
+	}
+});
 const viewersList = (options) => (options.client ?? client).get({
 	url: "/api/v1/documents/{id}/viewers",
 	...options
@@ -701,6 +713,23 @@ const workspaceDomainPattern = workspaceDomain.replaceAll(".", "\\.");
 const workspaceHostname = (subdomain) => `${subdomain}.${workspaceDomain}`;
 /** A valid workspace label: the subdomain of one workspace address, as a DNS label. */
 const workspaceLabelPattern = /^[a-z\d](?:[a-z\d-]{0,61}[a-z\d])?$/u;
+/**
+* Service names that are never a workspace. Migration `0002_personal_subdomains.sql` reserves
+* them in the address table, and readiness checks that the table still holds each one.
+*/
+const reservedWorkspaceSubdomains = [
+	"www",
+	"api",
+	"app",
+	"auth",
+	"admin",
+	"dashboard",
+	"docs",
+	"status",
+	"support",
+	"mail",
+	"pageship"
+];
 //#endregion
 //#region ../../packages/api-client/src/address.ts
 /** Generated TypeScript does not validate remote JSON, so check an address before showing it. */
@@ -858,7 +887,11 @@ async function getDocumentRevisions(baseUrl, id, options = {}) {
 	};
 	throw new Error("Invalid document revision listing response.");
 }
-/** Exact owner-only bytes of the current revision, or of one selected historical revision. */
+/**
+* Exact bytes of the current revision, or of one selected historical revision. The owner reads
+* any revision; another admitted account reads the current one of a public document, or of a
+* private one it is a viewer of.
+*/
 async function getDocumentContent(baseUrl, id, options = {}) {
 	const request = {
 		...requestOptions(baseUrl, options),
@@ -1061,6 +1094,31 @@ async function getGitHubUser(baseUrl, login, options = {}) {
 	throw new Error("Invalid GitHub user response.");
 }
 //#endregion
+//#region ../../packages/api-client/src/installations.ts
+async function requestInstallations(baseUrl, installationId, { signal, token } = {}) {
+	const timeout = AbortSignal.timeout(1e4);
+	const options = {
+		baseUrl,
+		credentials: token ? "omit" : "include",
+		headers: token ? { Authorization: `Bearer ${token}` } : void 0,
+		redirect: "error",
+		cache: "no-store",
+		throwOnError: false,
+		signal: signal ? AbortSignal.any([timeout, signal]) : timeout
+	};
+	const { data, response, error } = installationId === void 0 ? await installationsList(options) : await installationsRevoke({
+		...options,
+		cache: "default",
+		body: { installationId }
+	});
+	if (!response?.ok) throw new Error("Could not update CLI installations. Try again.", { cause: error });
+	if (data?.status === "signed_out" || data?.status === "uninvited" || data?.status === "unavailable" || data?.status === "revoked") return { status: data.status };
+	if (data?.status === "listed" && Array.isArray(data.installations) && data.installations.every((entry) => entry && typeof entry.id === "string" && entry.id.length > 0 && typeof entry.createdAt === "string" && Number.isFinite(Date.parse(entry.createdAt)) && typeof entry.expiresAt === "string" && Number.isFinite(Date.parse(entry.expiresAt)))) return data;
+	throw new Error("Invalid CLI installations response.");
+}
+/** Revoke one CLI installation. With `token`, a CLI revokes its own installation. */
+const revokeInstallation = (baseUrl, installationId, options) => requestInstallations(baseUrl, installationId, options);
+//#endregion
 //#region ../../packages/api-client/src/index.ts
 async function getWorkspace(baseUrl, options = {}) {
 	const timeout = AbortSignal.timeout(1e4);
@@ -1436,12 +1494,14 @@ const outcomes = {
 	published: "succeeded",
 	listed: "succeeded",
 	downloaded: "succeeded",
+	read: "succeeded",
 	visibility_updated: "succeeded",
 	restored: "succeeded",
 	viewers_updated: "succeeded",
 	skills_installed: "succeeded",
 	cli_updated: "succeeded",
 	cli_current: "succeeded",
+	logged_out: "succeeded",
 	authorization_pending: "pending",
 	expired: "pending",
 	signed_out: "pending",
@@ -1468,6 +1528,7 @@ const outcomes = {
 	invalid_attempt: "failed",
 	invalid_action: "failed",
 	invalid_file: "failed",
+	invalid_document: "failed",
 	invalid_output: "failed",
 	invalid_restore: "failed",
 	output_exists: "failed",
@@ -1493,10 +1554,12 @@ const commandNames = [
 	"status",
 	"login",
 	"whoami",
+	"logout",
 	"publish",
 	"list",
 	"history",
 	"download",
+	"read",
 	"visibility",
 	"viewers",
 	"restore",
@@ -1551,7 +1614,7 @@ function commandLine(command, args) {
 }
 //#endregion
 //#region package.json
-var version = "0.6.1";
+var version = "0.7.0";
 //#endregion
 //#region src/publish.ts
 const execute = promisify(execFile);
@@ -2270,6 +2333,48 @@ async function identify(serverValue, signal) {
 	}
 }
 //#endregion
+//#region src/document-reference.ts
+const documentPath = /^\/d\/([^/-]+)(?:-[^/]+)?(?:\/revisions\/([^/]+))?$/u;
+/** True for any URL, so the value is read as a link rather than as a malformed ID. */
+const isUrl = (value) => URL.canParse(value);
+/**
+* Reads a document ID from `list`, or a document or revision link the user pasted.
+* A link must be one a workspace host would serve, on any workspace: the server decides
+* access, so a link to a document this account can't read gets the same answer as an
+* unknown ID.
+* `revisionId` is an explicit `--revision`; it must agree with a revision link.
+*/
+function documentReference(value, revisionId) {
+	const named = isDocumentId(value) ? { documentId: value } : documentLink(value);
+	if (!named) return {
+		status: "invalid_document",
+		message: `${value} is not a Pageship document. Use a six-character document ID from list, or a document link such as https://<workspace>.${workspaceDomain}/d/<id>-<slug>.`
+	};
+	if (revisionId && named.revisionId && revisionId.toLowerCase() !== named.revisionId.toLowerCase()) return {
+		status: "invalid_document",
+		message: `The link names revision ${named.revisionId}, but --revision names ${revisionId}. Use one of them.`
+	};
+	const revision = named.revisionId ?? revisionId;
+	return {
+		documentId: named.documentId,
+		...revision ? { revisionId: revision } : {}
+	};
+}
+function documentLink(value) {
+	if (!isUrl(value)) return;
+	const url = new URL(value);
+	const suffix = `.${workspaceDomain}`;
+	const label = url.hostname.slice(0, -suffix.length);
+	if (url.protocol !== "https:" || url.port || url.username || url.password || !url.hostname.endsWith(suffix) || !workspaceLabelPattern.test(label) || reservedWorkspaceSubdomains.some((name) => name === label)) return;
+	const [, documentId, revisionId] = documentPath.exec(url.pathname) ?? [];
+	if (!isDocumentId(documentId)) return;
+	if (revisionId === void 0) return { documentId };
+	return isRevisionId(revisionId) ? {
+		documentId,
+		revisionId
+	} : void 0;
+}
+//#endregion
 //#region src/documents.ts
 /** `1 viewer`, `2 viewers`. */
 const viewerCount = (count) => `${count} viewer${count === 1 ? "" : "s"}`;
@@ -2386,12 +2491,16 @@ function invalidOutput(output, error) {
 		message: `Could not write ${output}. ${error instanceof Error ? error.message : "Check the path and try again."}`
 	};
 }
-function downloadDocument(options) {
+/** `document` is an ID from `list` or a document or revision link; see `documentReference`. */
+async function downloadDocument(options) {
+	const reference = documentReference(options.document, options.revisionId);
+	if ("status" in reference) return reference;
+	const { documentId, revisionId } = reference;
 	const output = resolve(options.output);
 	return asOwner(options.server, options.signal, async ({ origin }, request) => {
-		const bytes = await getDocumentContent(origin, options.documentId, {
+		const bytes = await getDocumentContent(origin, documentId, {
 			...request,
-			revisionId: options.revisionId
+			revisionId
 		});
 		let file;
 		try {
@@ -2414,11 +2523,48 @@ function downloadDocument(options) {
 		await file.close();
 		return {
 			status: "downloaded",
-			documentId: options.documentId,
-			revisionId: options.revisionId ?? null,
+			documentId,
+			revisionId: revisionId ?? null,
 			output,
 			byteLength: bytes.byteLength,
-			message: `Saved ${bytes.byteLength} bytes of ${options.documentId}${options.revisionId ? ` revision ${options.revisionId}` : ""} to ${output}.`
+			message: `Saved ${bytes.byteLength} bytes of ${documentId}${revisionId ? ` revision ${revisionId}` : ""} to ${output}.`
+		};
+	});
+}
+/**
+* Reads a document's HTML for printing. `document` is an ID or a link, as for download. The
+* owner reads any revision; anyone reads a public document's current one, and a viewer a
+* private one's. The server answers a document this
+* account can't read like a missing one, so one message covers all three.
+*/
+async function readDocument(options) {
+	const reference = documentReference(options.document);
+	if ("status" in reference) return reference;
+	const { documentId, revisionId } = reference;
+	return asOwner(options.server, options.signal, async ({ origin }, request) => {
+		let bytes;
+		try {
+			bytes = await getDocumentContent(origin, documentId, {
+				...request,
+				revisionId
+			});
+		} catch (error) {
+			if (isRefusal(error) && error.status === "unavailable") return {
+				status: "unavailable",
+				documentId,
+				revisionId: revisionId ?? null,
+				message: `${options.document} is unavailable. It doesn't exist, was deleted, or this account can't read it.${revisionId ? " Only the owner can read an earlier revision." : ""} Check the link, and that this installation is signed in as the owner or a viewer if it is private.`
+			};
+			throw error;
+		}
+		return {
+			status: "read",
+			documentId,
+			revisionId: revisionId ?? null,
+			byteLength: bytes.byteLength,
+			html: new TextDecoder().decode(bytes),
+			bytes,
+			message: `Read ${bytes.byteLength} bytes of ${documentId}${revisionId ? ` revision ${revisionId}` : ""}.`
 		};
 	});
 }
@@ -2489,6 +2635,111 @@ function restoreRevision(options) {
 	});
 }
 //#endregion
+//#region src/logout.ts
+const errorText = (error) => error instanceof Error ? error.message : String(error);
+const exists = (path) => lstat(path).then(() => true, (error) => {
+	if (error.code === "ENOENT") return false;
+	throw error;
+});
+/**
+* Sign this installation out: revoke its session on the server, as the dashboard's Revoke
+* access does, then delete the stored credential. The credential is deleted only once the
+* server confirms the session is gone, so a failure never leaves a live session that the user
+* believes has ended.
+*/
+async function logout(serverValue, signal) {
+	const selection = selectServer(serverValue);
+	const server = selection.origin;
+	const retry = {
+		command: "logout",
+		args: [...selection.args]
+	};
+	const retryLine = commandLine(retry.command, retry.args);
+	/** A failure that keeps the credential. Only a retry that can succeed gets `next`. */
+	const credentialKept = (status, reason, retryable = true) => ({
+		status,
+		message: `${reason} Your credential is kept, so this installation is still signed in.${retryable ? ` Run ${retryLine} to try again.` : ""}`,
+		...retryable ? { next: retry } : {}
+	});
+	const notSignedIn = "This installation is not signed in, so there was nothing to sign out of.";
+	let store;
+	try {
+		const directory = configDirectory();
+		if (isAbsolute(directory) && !await exists(directory)) return {
+			status: "logged_out",
+			revoked: false,
+			message: notSignedIn
+		};
+		store = await credentialStore(server);
+	} catch (error) {
+		return credentialKept("request_failed", `Could not open the stored credential. ${errorText(error)}`);
+	}
+	try {
+		const credentials = await store.read();
+		const discarded = credentials.pending ? " An authorization code waiting for approval was discarded. If you approved it, its session may still be listed under CLI installations in the dashboard; revoke it there." : "";
+		if (!credentials.token) {
+			if (credentials.pending) await store.write({});
+			return {
+				status: "logged_out",
+				revoked: false,
+				message: `${notSignedIn}${discarded}`
+			};
+		}
+		const token = credentials.token;
+		let revoked;
+		try {
+			const compatibility = await checkCompatibility(server, { signal });
+			if (compatibility.status !== "compatible") return {
+				...compatibility,
+				...credentialKept(compatibility.status, compatibility.message, false)
+			};
+			const access = await getWorkspace(server, {
+				token,
+				signal
+			});
+			const notAdmitted = {
+				status: "uninvited",
+				message: `This account is no longer admitted to this Pageship server, so the server already refuses every request from this installation. It did not remove the installation, though. To sign out fully, ask the server owner to admit the account again and then run ${retryLine}, or to remove the installation. Your credential is kept.`
+			};
+			if (access.status === "uninvited") return notAdmitted;
+			if (access.status === "signed_out") revoked = false;
+			else if (!access.installation) return credentialKept("unsupported", "This server does not report the CLI installation, so the CLI cannot revoke it. Update the server, or revoke the installation in the dashboard under CLI installations.", false);
+			else {
+				const result = await revokeInstallation(server, access.installation.id, {
+					token,
+					signal
+				});
+				if (result.status === "uninvited") return notAdmitted;
+				if (result.status === "revoked") revoked = true;
+				else if (result.status === "signed_out") revoked = false;
+				else return credentialKept("request_failed", "The server did not revoke this installation.");
+			}
+		} catch (error) {
+			if (signal.aborted) return credentialKept("interrupted", "Sign-out was interrupted, and the server may not have revoked this installation.");
+			return credentialKept("request_failed", `Could not sign out through the Pageship server. ${errorText(error)}`);
+		}
+		try {
+			await store.write({});
+		} catch (error) {
+			return {
+				status: "request_failed",
+				revoked,
+				message: `The server ${revoked ? "revoked this installation" : "had already revoked or expired this credential"}, but the stored credential could not be deleted. ${errorText(error)} Run ${retryLine} to delete it.`,
+				next: retry
+			};
+		}
+		return {
+			status: "logged_out",
+			revoked,
+			message: `${revoked ? "Signed out. The server revoked this installation, and its stored credential is deleted." : "Signed out. The server had already revoked or expired this credential, and the stored copy is deleted."}${discarded}`
+		};
+	} catch (error) {
+		return credentialKept("request_failed", `Could not use the stored credential. ${errorText(error)}`);
+	} finally {
+		await store.close();
+	}
+}
+//#endregion
 //#region src/skill-files.ts
 const frontmatter = /^---\r?\n([\s\S]*?)\r?\n---(?=\r?\n|$)/u;
 /** The CLI version a packed SKILL.md was stamped with, or undefined for an unstamped one. */
@@ -3286,6 +3537,7 @@ const login = Command.make("login", {
 	});
 })).pipe(Command.withDescription("Authorize this installation through a browser and choose your workspace address."));
 const whoami = Command.make("whoami", { server: serverFlag }, ({ server }) => authCommand("whoami", (signal) => identify(Option.getOrUndefined(server), signal))).pipe(Command.withDescription("Identify your personal workspace using the stored credential."));
+const logoutCommand = Command.make("logout", { server: serverFlag }, ({ server }) => authCommand("logout", (signal) => logout(Option.getOrUndefined(server), signal))).pipe(Command.withDescription("Sign this installation out: revoke its access on the server, then delete the stored credential."));
 const idempotencyKeyFlag = Flag.string("idempotency-key").pipe(Flag.filter((value) => /^[A-Za-z0-9_-]{8,128}$/u.test(value), () => "Use an 8-128 character idempotency key containing letters, digits, underscores or hyphens."), Flag.withDescription("Retry an uncertain operation with the key its result returned."), Flag.optional);
 const publishCommand = Command.make("publish", {
 	file: Argument.string("file"),
@@ -3330,18 +3582,34 @@ const history = Command.make("history", {
 	cursor: Option.getOrUndefined(cursor),
 	signal
 }))).pipe(Command.withDescription("List a document's revisions, newest first, 50 per page."));
+const documentArgument = Argument.string("document").pipe(Argument.filter((value) => isDocumentId(value) || isUrl(value), () => "Use a six-character document ID from list, or the document's https:// link."), Argument.withDescription("Six-character document ID from list, or the document's link, including a revision link."));
 const download = Command.make("download", {
-	documentId: documentIdArgument,
+	document: documentArgument,
 	server: serverFlag,
 	output: Flag.string("output").pipe(Flag.withDescription("New file to write the exact HTML bytes to. Existing files are kept.")),
 	revision: revisionFlag("revision", "Download this historical revision instead of the current one.").pipe(Flag.optional)
-}, ({ documentId, server, output, revision }) => authCommand("download", (signal) => downloadDocument({
+}, ({ document, server, output, revision }) => authCommand("download", (signal) => downloadDocument({
 	server: Option.getOrUndefined(server),
-	documentId,
+	document,
 	output,
 	revisionId: Option.getOrUndefined(revision),
 	signal
-}))).pipe(Command.withDescription("Save a document's current or historical HTML to a new file. Visibility is unchanged."));
+}))).pipe(Command.withDescription("Save a document's current or historical HTML to a new file, by ID or link. Visibility is unchanged."));
+const read = Command.make("read", {
+	document: documentArgument,
+	server: serverFlag
+}, ({ document, server }) => {
+	let bytes;
+	return authCommand("read", async (signal) => {
+		const { bytes: read, ...result } = await readDocument({
+			server: Option.getOrUndefined(server),
+			document,
+			signal
+		});
+		bytes = read;
+		return result;
+	}, (result) => bytes ? process.stdout.write(bytes) : console.error(result.message));
+}).pipe(Command.withDescription("Print a document's current HTML to stdout, by ID or link: your own, a public one or one shared with you. The owner can also read a revision link."));
 const visibility = Command.make("visibility", {
 	documentId: documentIdArgument,
 	visibility: Argument.choice("visibility", ["private", "public"]),
@@ -3402,7 +3670,8 @@ function sameCommand(name) {
 		args: rest
 	};
 }
-function authCommand(name, operation) {
+/** Runs one command and reports its result. `print` replaces the human output of the message. */
+function authCommand(name, operation, print) {
 	return Effect.promise(async () => {
 		const controller = new AbortController();
 		const interrupt = () => controller.abort();
@@ -3428,6 +3697,7 @@ function authCommand(name, operation) {
 				console.error(`${name === "status" ? "Could not check status" : name === "skills" ? "Could not install the Pageship skills" : name === "update" ? "Could not update Pageship" : "Pageship request failed"}: ${result.message}`);
 				return;
 			}
+			if (print) return print(result);
 			console.log(result.message);
 			if (typeof result.verificationUriComplete === "string" && typeof result.userCode === "string" && result.next) console.log(`Open ${result.verificationUriComplete}\nCheck code ${result.userCode}.\nThen run: ${commandLine(result.next.command, result.next.args)}`);
 		} finally {
@@ -3436,14 +3706,16 @@ 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, viewers and restore. Install the Pageship skills for your agents with skills install, and update the CLI with update."), 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. Sign it out with logout. Manage published documents with list, history, download, visibility, viewers and restore. Read a document you own or were shared, by ID or link, with read. Install the Pageship skills for your agents with skills install, and update the CLI with update."), Command.withSubcommands([
 	status,
 	login,
 	whoami,
+	logoutCommand,
 	publishCommand,
 	list,
 	history,
 	download,
+	read,
 	visibility,
 	viewers,
 	restore,
@@ -3451,6 +3723,17 @@ const command = Command.make("pageship").pipe(Command.withDescription("Pageship
 	updateCommand
 ]), Command.withGlobalFlags([jsonFlag]));
 const effectiveArgs = args.every((arg, index) => arg === "--json" || arg.startsWith("--json=") && booleanValue(arg.slice(7)) !== void 0 || index > 0 && args[index - 1] === "--json" && booleanValue(arg) !== void 0) ? [...args, "--help"] : args;
+/** The subcommand named before `--`, skipping global flags and the values they take. */
+function subcommandName() {
+	for (let index = 0; index < flagArgs.length; index++) {
+		const arg = flagArgs[index];
+		if (arg === "--json" && booleanValue(flagArgs[index + 1]) !== void 0) index++;
+		else if (arg === "--log-level" || arg === "--completions") index++;
+		else if (!arg.startsWith("-")) return arg;
+	}
+}
+const builtInFlag = /^(?:--help|-h|--version|-v|--completions|--wizard)(?:=|$)/u;
+const readsDocument = !json && subcommandName() === "read" && !flagArgs.some((arg) => builtInFlag.test(arg));
 const program = Command.runWith(command, {
 	version,
 	renderErrors: !json
@@ -3475,7 +3758,10 @@ await Effect.runPromise(json ? program.pipe(Effect.provideService(CliOutput.Form
 	...console,
 	log: () => {},
 	error: () => {}
-}), Effect.provide(CliConfig.layer({ builtIns: [GlobalFlag.Help, GlobalFlag.Version] }))) : program);
+}), Effect.provide(CliConfig.layer({ builtIns: [GlobalFlag.Help, GlobalFlag.Version] }))) : readsDocument ? program.pipe(Effect.provideService(Console.Console, {
+	...console,
+	log: console.error
+})) : program);
 if (json) {
 	if (!envelope) settle(null, {
 		status: "internal_error",

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 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.
+description: Publish an HTML file to Pageship, read Pageship documents and manage what is published. Use when the user pastes or names a Pageship document link (https://<workspace>.pageship.dev/d/<id>, not a link to the pageship.dev site, the dashboard or the API), or 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 or out of Pageship. To write, edit, rename or move a document, load pageship-docs instead.
 license: MIT
 metadata:
-  version: "0.6.1"
+  version: "0.7.0"
 ---
 
 # Pageship
@@ -91,6 +91,16 @@ On `reauthentication_required`, ask the user to sign in to the Pageship dashboar
 
 When `login` returns `cancelled`, `interrupted` or `request_failed` with a `user`, authorization succeeded and the credential is kept, but no address is selected. Run the returned `next` when the user is ready.
 
+## Sign out
+
+Only when the user asks to sign this installation out of Pageship, run:
+
+```sh
+pageship --json logout
+```
+
+On `logged_out`, the installation is signed out and its credential is deleted. `revoked: false` means there was nothing to revoke, which also counts as signed out. Report the `message` either way: it can ask the user to revoke a leftover session in the dashboard. On any other status, report the `message`, which says whether the installation is still signed in. Run the returned `next`, when there is one, only when the user wants to retry.
+
 ## Publish
 
 Set the shell placeholder `PAGESHIP_FILE` to one nonempty `.html` or `.htm` file. Pageship uses the server's configured per-file size limit. A new document is private. An existing source-path match does not overwrite a document.
@@ -141,6 +151,10 @@ When the user names the people to share it with, keep it private and add them as
 
 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).
 
+## Read a document link
+
+A document link is `https://<workspace>.pageship.dev/d/<id>`, often followed by `-<slug>` and sometimes by `/revisions/<revisionId>`. When the user pastes one or asks about one, read it with `pageship read`, as in [read](references/read.md), instead of fetching it: a private document's link answers a fetch like a missing page, and `read` also reads public documents. Fetch a document link only when the CLI isn't installed or the user doesn't want to sign in; that works for public documents alone. Links to `pageship.dev` itself, `app.pageship.dev` or `api.pageship.dev` are not document links; fetch or open them as usual.
+
 ## Use another server
 
 The CLI uses the hosted Pageship service by default. Only when the user names another Pageship server, such as a local development server, add `--server <origin>` to every command you start yourself. Returned `next` and `resolutions` arguments already carry that server, so run them unchanged.
@@ -150,12 +164,13 @@ The CLI uses the hosted Pageship service by default. Only when the user names an
 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.
+- [Read](references/read.md): print a document's current HTML, by its ID or the link the user pasted, for a document the user owns, a public one, or one the user was added to as a viewer.
+- [Download](references/download.md): save a document's HTML to a file, current or from an earlier revision, by its ID or the link the user pasted.
 - [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.
+Deleting a document, recovering a deleted one, changing a document's display title and revoking another 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.
 
 ## Handle other outcomes
 

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

@@ -1,9 +1,9 @@
 # Download
 
-To read a document's HTML, run:
+To save a document's HTML to a file, run:
 
 ```sh
 pageship --json download "$PAGESHIP_DOCUMENT" --output "$PAGESHIP_OUTPUT"
 ```
 
-Set `PAGESHIP_DOCUMENT` to the document's `id` from `list`, and `PAGESHIP_OUTPUT` to a path that does not exist. For a historical revision, add `--revision <revisionId>` with an ID from `history`. The bytes go only to that file. On `output_exists`, nothing was written or replaced; choose another path. A download never changes the document or its visibility.
+Set `PAGESHIP_DOCUMENT` to the document's `id` from `list`, or to the document link the user pasted, such as `https://<workspace>.pageship.dev/d/<id>-<slug>`; you don't need `list` to find the ID. Set `PAGESHIP_OUTPUT` to a path that does not exist. For a historical revision, add `--revision <revisionId>` with an ID from `history`, or pass the revision link, which ends in `/revisions/<revisionId>`. On `invalid_document`, the value is not a Pageship document link; ask the user for the right link or ID. The bytes go only to that file. On `output_exists`, nothing was written or replaced; choose another path. A download never changes the document or its visibility. For another person's document, public or shared with the user, download gets the current revision only. To read HTML without writing a file, use [read](read.md).

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

@@ -0,0 +1,17 @@
+# Read
+
+To read a document's HTML, run:
+
+```sh
+pageship --json read "$PAGESHIP_DOCUMENT"
+```
+
+Set `PAGESHIP_DOCUMENT` to the document link the user pasted, such as `https://<workspace>.pageship.dev/d/<id>-<slug>`, or to the document's `id` from `list`. On `read`, the document's HTML is in `html`, and `revisionId` is `null` for the current revision. Without `--json`, the command prints the HTML alone on standard output, so you can redirect it to a file.
+
+Reading works for any public document, and for a private document's owner and its viewers, the GitHub accounts the owner shared it with, signed in to this installation. The owner can also pass a revision link, which ends in `/revisions/<revisionId>`, to read that revision; a viewer reads the current revision only.
+
+- `invalid_document`: the value isn't a document link. Links to the pageship.dev site, the dashboard and the API are refused before any request. Fetch or open those as usual.
+- `unavailable`: the document doesn't exist, was deleted, or the signed-in account can't read it. Pageship doesn't say which. Tell the user, and ask them to check the link and which GitHub account they signed in with; `pageship --json whoami` shows it. Someone who should have access needs the owner to add their account as a viewer.
+- `signed_out`: sign in as [Sign in](../SKILL.md#sign-in) describes, then read again.
+
+Reading never changes the document, and doesn't count as a view.

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

@@ -3,7 +3,7 @@ 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."
 license: MIT
 metadata:
-  version: "0.6.1"
+  version: "0.7.0"
 ---
 
 # Chart

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

@@ -3,7 +3,7 @@ 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."
 license: MIT
 metadata:
-  version: "0.6.1"
+  version: "0.7.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.6.1"
+  version: "0.7.0"
 ---
 
 # Decision record

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

@@ -3,7 +3,7 @@ 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."
 license: MIT
 metadata:
-  version: "0.6.1"
+  version: "0.7.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.6.1"
+  version: "0.7.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.6.1"
+  version: "0.7.0"
 ---
 
 # Explainer

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

@@ -3,7 +3,7 @@ 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."
 license: MIT
 metadata:
-  version: "0.6.1"
+  version: "0.7.0"
 ---
 
 # Interaction

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

@@ -3,7 +3,7 @@ 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."
 license: MIT
 metadata:
-  version: "0.6.1"
+  version: "0.7.0"
 ---
 
 # Key figures

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

@@ -3,7 +3,7 @@ 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."
 license: MIT
 metadata:
-  version: "0.6.1"
+  version: "0.7.0"
 ---
 
 # Media

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

@@ -3,7 +3,7 @@ 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."
 license: MIT
 metadata:
-  version: "0.6.1"
+  version: "0.7.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.6.1"
+  version: "0.7.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.6.1"
+  version: "0.7.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.6.1"
+  version: "0.7.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.6.1"
+  version: "0.7.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.6.1"
+  version: "0.7.0"
 ---
 
 # Spec

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

@@ -3,7 +3,7 @@ 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."
 license: MIT
 metadata:
-  version: "0.6.1"
+  version: "0.7.0"
 ---
 
 # Table

package/package.json

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