pageship 0.1.1 → 0.3.0

package/README.md

@@ -1,122 +1,32 @@
-# Pageship
+# Pageship CLI
 
-Pageship is an HTML publishing service in development. This CLI checks a server's API
-compatibility, authorizes an installation through a browser, and identifies your
-personal workspace. It publishes HTML documents and revisions behind stable addresses. Private browser delivery requires the owner to sign in.
+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.
 
-Requires Node.js 24.11 or newer.
+The full reference, with every command, option and result, is at https://pageship.dev/docs/cli.
 
-```sh
-npx pageship
-npx pageship --help
-npx pageship --version
-npx pageship status --server http://localhost:8787
-npx pageship --json status --server http://localhost:8787
-```
-
-`status` accepts an HTTP or HTTPS server base URL and checks the API major this CLI
-requires against the majors advertised by the server. Package versions do not
-determine API compatibility. The request times out after 10 seconds.
-
-The `--json` flag is global and may appear before or after `status`, including on
-help, version, and invalid invocations. JSON mode writes one JSON value to stdout
-without human output or prompts. Like other flags, `--json` after the `--` separator
-is treated as an argument. Interactive wizard and shell-completion options are
-available only in human mode.
-
-- Exit `0`: compatible server, help, or version.
-- Exit `1`: invalid arguments, network failure, or invalid server response.
-- Exit `2`: incompatible API major. The result explains whether the CLI or server
-  needs updating, or the requested major is unsupported.
-
-JSON status results contain `ok`, `command: "status"`, `status`, `requiredApiMajor`,
-`server`, and `message`. `status` is `compatible`, `client_too_old`, `server_too_old`,
-or `unsupported`. The server object contains `serverVersion`, `currentApiMajor`,
-and `supportedApiMajors`. Failures contain `ok: false` and an `error` object with
-`code` and `message`; codes are `usage_error`, `request_failed`, or `internal_error`.
-Help and version use `command: "help"` and `command: "version"`, respectively.
-
-## Browser authorization
-
-Run `pageship login --server https://api.example.com`, open the displayed link on
-any machine, and approve the code using your invited GitHub account. Interactive
-terminals wait for approval. JSON and non-TTY calls return immediately with a link,
-code and completion arguments; then run `pageship login --complete --server
-https://api.example.com`. Run `pageship whoami --server https://api.example.com`
-to reuse the stored credential in a new process. Add global `--json` for structured
-results. Pending or denied authorization exits 2, success exits 0, request/storage
-failures exit 1, and interrupted waiting exits 130.
-
-Credentials are plaintext JSON outside projects. POSIX uses an owner-only directory
-and 0600 files. Windows uses the current user's local app data and inherits
-user-profile permissions; the CLI does not configure Windows ACLs.
-`PAGESHIP_CONFIG_DIR` selects an absolute private directory. They are bound to the
-exact HTTPS server origin; HTTP is allowed only on loopback for development.
-Use `login --restart` for a new code. Address selection and publication are not
-required for authorization. No credentials appear in command output.
+## Install
 
-## Publish HTML
+The CLI requires Node.js 24.11 or newer. Install it globally with your package manager:
 
-Run `pageship publish report.html --server https://api.example.com` after login.
-Absolute file arguments work too. Add `--json` for structured success, source-path
-collisions and address choices. If publication fails after transfer, retry with
-the returned `--idempotency-key`. Reusing that key with the same input returns the
-same document; a different input produces a conflict. Ordinary path collisions
-never update or duplicate a document without an explicit choice.
-
-In a terminal, select `o <number>` to open a matching document, `r <number>` to
-revise it, `n` to create a separate private document, or `q` to cancel. Opening and
-cancellation do not change published content. JSON returns candidates and
-`resolutions` containing complete follow-up command arguments. Run those arguments
-in another invocation to choose explicitly.
-
-Use `--new` to create a separate document even when its source path matches. Use
-`--revise <documentId> --expected-revision <revisionId>` from a returned candidate
-to publish a revision. A concurrent publication returns `revision_conflict` and
-does not overwrite the newer revision. Revisions retain document identity, URL,
-visibility and old immutable content. An interrupted action returns `next` arguments
-including its operation key and selected target; repeat those with unchanged bytes.
-Explicit actions require a server that advertises support; an older server returns
-upgrade guidance before HTML upload.
-
-The default per-file limit is 10,000,000 bytes, configurable by the server. The CLI
-checks it before upload. Source paths are relative to the file's Git root, containing
-working directory, or parent for outside-cwd non-Git files. Git origin URLs contribute
-a normalized, credential-free hashed context. No local manifest is required.
-
-Generated address choices use `--address-choice <choiceId>` or
-`--refresh-addresses`; arbitrary subdomain input is not supported. An interactive
-terminal can select, refresh or cancel. JSON and non-TTY output never waits for a
-choice. Published results exit 0; unresolved choices, collisions, access and size
-failures exit 2; file/request/usage failures exit 1. See the repository's
-[publishing contract](../../docs/publishing.md) for details.
+```sh
+npm i -g pageship
+pnpm add -g pageship
+bun add -g pageship
+```
 
-## Development
+Then run `pageship --version` to check that the shell finds it. To have an agent install the CLI and the Pageship skills and sign you in, give it the [setup guide](https://pageship.dev/setup-guide) instead.
 
-Install dependencies from the workspace root as described in the
-[root README](../../README.md). From this directory:
+## Get started
 
 ```sh
-pnpm run check
-pnpm run build
-node dist/cli.mjs --help
-npm pack --dry-run
+pageship login                 # authorize this installation in your browser
+pageship skills install        # install the Pageship skills for your agents
+pageship status                # check that you are ready to publish
+pageship publish report.html   # publish a file as a private document
 ```
 
-The CLI uses TypeScript and Effect v4's unstable CLI API. Effect and its Node
-platform package are pinned to matching release candidates.
-The shared generated API client is a workspace development dependency bundled
-into `dist/cli.mjs`. Installing the published CLI does not require the private
-workspace package or a checkout of this repository.
-
-## Revoke installation access
-
-`whoami --server <origin>` shows this CLI installation's non-secret ID. JSON mode
-returns it in `installation.id`. Match that ID in the signed-in dashboard's CLI
-installations list and select Revoke access. The next protected request returns
-exit 2 with sign-in guidance; other installations remain authorized. Run `login`
-with the same server to authorize again explicitly.
+Add `--json` to any command for one structured result, which is what agents use. Run `pageship --help`, or any command with `--help`, to see its options.
 
 ## License
 
-UNLICENSED. No open-source license is granted.
+UNLICENSED. No open-source license is granted for the CLI. The Pageship skills in `dist/skills` are MIT licensed, as `dist/skills/LICENSE` states.