saypsst 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,58 @@
-# Temporary Holding Version
+# PSST
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Install [PSST](https://saypsst.com) on your site, and check it in production. PSST publishes pages that make your brand show up in AI answers, on your own domain, under a path prefix it owns (default `/resources`), with no deploy after this one-time install.
+
+## Quick start
+
+1. Copy your site id from the PSST dashboard (Settings › Connections).
+2. In your site's folder: `npx saypsst init --site <site id>`. It checks before it writes, and prints any edit it will not make for you.
+3. Commit and deploy. Then check it in production: `npx saypsst doctor --wait`.
+
+```sh
+npx saypsst init --site site_xxxxxxxxxxxxxxxx
+# commit, deploy, then:
+npx saypsst doctor --wait
+```
+
+Briefs for Orchestrapay and Enrow (the exact prompt, the PR contents, host notes): `features/publish-integration-2026-10-28/install-briefs/`.
+
+Or paste this to your coding agent: *Run `npx saypsst init --site site_xxxxxxxxxxxxxxxx` and follow the PSST skill.* `init` copies the skills into `.claude/skills/` and `.agents/skills/`: `psst` (the plumbing) and `psst-tasks` (below).
+
+- **No secrets.** The site id is public. PSST never asks for a key, token or deploy access.
+- **Zero runtime dependencies, no install scripts.** One bundled file, Node 20 or later.
+- **Idempotent.** `init` marks with ✓ what is in place, does only what is missing, never overwrites a file you edited, and prints the exact edit for a file too unusual to change.
+
+## What `init` does
+
+| Site | Detected by | What it writes |
+| --- | --- | --- |
+| Next.js App Router (15, 16), any host | `next` in `package.json` and `app/` or `src/app/` | `@saypsst/next` (exact version) in `package.json` and the install; `psst.config.ts`; `app/(psst){prefix}/[...slug]/page.tsx`, `sitemap.xml/route.ts`, `%5Fpsst/style.css/route.ts`, `%5Fpsst/verify/route.ts`; `app/about/page.tsx` / `app/llms.txt/route.ts` only when the dashboard claimed them and the app does not serve them; `proxy.ts` (`middleware.ts` on Next 15) with `withPsst()`, or the printed wrap for an existing one; the sitemap line in `public/robots.txt` (printed for `app/robots.ts`). The files are those of `@saypsst/next`'s README. |
+| Static site on Vercel | `vercel.json` without Next (or `--mode vercel_static`) | Rewrites `{prefix}/:path*` → `https://edge.saypsst.com/s/{site}{prefix}/:path*` (and claimed root paths) inserted first in `vercel.json`, every other byte kept; the sitemap line in `robots.txt`. |
+| Anything else | | Nothing but the skill; prints how to route the prefix (Cloudflare Worker, nginx, CloudFront, Next Pages Router rewrites). |
+
+All modes: the two skills, and with `--agents-md` a two-line note in `AGENTS.md`. Before writing anything, `init` checks the site id with PSST, that the prefix is free in the repository and on the live site, and that the app is supported (App Router, Next ≥ 15, no Cache Components).
+
+`init` options: `--site`, `--site-name` (Next.js: overrides the brand name for Open Graph and JSON-LD; defaults to the dashboard's, then `psst.config.ts`), `--prefix` / `--domain` (must equal the dashboard's; default to it), `--mode next|vercel_static|proxy`, `--agents-md`, `--no-install`, `--dry-run`, `--dir <path>`. For local testing: `--edge <origin>` (or `PSST_EDGE`; `http:` only on localhost), `--site-url <origin>` (the live site to check the prefix on, default `https://{domain}`), `--psst-next <spec>` (dependency spec for `@saypsst/next`, for example a tarball path).
+
+## Let your agent do your PSST tasks
+
+Every PSST brief says who does it once you approve it: **PSST** (mentions, listings, community, pages on PSST's own paths) or **your agent** (changes to your existing pages and stack). The `psst-tasks` skill is how your agent does its share.
+
+1. Approve briefs in the PSST dashboard (Overview ✓). The ones marked *Done by <Brand>'s agent* are now your agent's.
+2. Connect the PSST connector (`https://app.saypsst.com/api/mcp`) in Claude Code or Codex (setup: https://app.saypsst.com/connectors).
+3. Tell your agent: *Do my PSST tasks. Don't stop until they're done.* It lists its approved briefs, makes each change in this repository, opens a pull request the way your repository works, and marks a brief done only once the change is live on production.
+4. Optional: a nightly run ("Anything to implement from PSST?"). `skills/psst-tasks/routine.md` has the prompt.
+
+Your agent never approves or declines briefs, never acts off your site and never touches PSST's own paths.
+
+## `doctor`
+
+Fetches the production site (or `--url <origin>`) as a browser and as GPTBot, OAI-SearchBot, ClaudeBot, PerplexityBot and Googlebot, without following redirects, and checks: the domain proof (`{prefix}/_psst/verify` equals the edge's), the stylesheet, the sitemap lists every published page, `/llms.txt` when claimed, and for up to three published pages: 200, the published `psst-version`, the canonical `https://{domain}{path}`, no `noindex`, the full text without JavaScript, identical content for people and crawlers; robots.txt policy for search, user-fetch and training crawlers separately. Probes send `X-Psst-Doctor: 1`, so they are never counted as crawler hits. `--wait` polls while a check waits on a deploy or a cache (up to `--timeout`, default 300 s). It reads the site from `psst.config.ts` or the `vercel.json` rewrite, or `--site`.
+
+## `status`
+
+The site's mode, prefix, claimed root paths, published pages with their 12-character versions, and withdrawn paths.
+
+## Output and exit codes
+
+`--json` prints one object per command; the JSON Schemas are in `schemas/` (`index.json` maps them). Exit codes: **0** done · **1** failed (message id `P01`…`P44`, explained in the skill's `troubleshooting.md`) · **2** usage · **3** waiting, run the same command again · **4** PSST or the site unreachable from here.