@siteoshq/cli 1.2.0 → 1.4.0

package/README.md

@@ -1,7 +1,7 @@
 # SiteOS CLI
 
 `@siteoshq/cli` exposes one `siteos` binary for Auth, common Projects, Pulse, Cookie, Forms,
-Search, Trace and Integrations. This source prepares version 1.2.0; publishing is a separate release.
+Search, Trace, SEO and Integrations. This source prepares version 1.3.0; publishing is a separate release.
 Node.js 22 or newer is required.
 
 ## Install and authenticate
@@ -69,7 +69,7 @@ siteos project environment connect forms --environment production --resource '<f
 Omit `--resource` to create a new local environment. `siteos project environment list` reports the
 common catalog and connections. Forms/Search/Trace operational `--environment` flags accept common
 slugs and resolve explicit native bindings; without the flag, commands use the selected environment.
-Pulse/Cookie use separate bound resources per environment. Missing bindings fail without a fallback.
+Pulse/Cookie/SEO use separate bound resources per environment. Missing bindings fail without a fallback.
 Manage names and website URLs with `project update` and `project environment update <slug>`.
 Cookie/Trace published addresses remain unchanged until explicit republication.
 
@@ -136,6 +136,35 @@ snippet is unavailable until runtime publication succeeds. Integrations connecti
 Organization; provider authorization opens the shared browser flow, and notification destinations
 are connected explicitly by each service.
 
+### SEO (prepared for release)
+
+Check `siteos seo --help` before use; install a matching release only after it is published. An
+SEO-capable server returns SEO in its Project service catalog, which older strict CLI parsers may
+reject. Coordinate the CLI update before that server rollout, then publish the matching plugin.
+
+```sh
+siteos project connect seo --json
+siteos seo status --environment production --json
+siteos seo audit run --environment production --json
+siteos seo audit list --json
+siteos seo audit show '<audit-id>' --json
+siteos seo pages --audit '<audit-id>' --json
+siteos seo issues --audit '<audit-id>' --json
+siteos seo changes --audit '<audit-id>' --state resolved --json
+siteos seo recheck --audit '<audit-id>' --url https://example.com/pricing --json
+```
+
+Setup performs no crawl. `audit run` queues a full HTML audit; `recheck` queues one previously
+observed URL. Read the returned audit ID until a terminal state; a queued response is not a result.
+`audit cancel '<audit-id>'` revokes further work. Pages and changes are paginated with `--page`.
+
+`issue ignore` and `issue restore` require `--audit`, `--url`, `--rule`, `--reason` and the current
+`--revision` (0 before the first decision). They use a distinct issue-write scope. Read back the
+decision after success; a revision conflict requires refreshing it. Ignore never means resolved.
+All SEO commands resolve the selected common Project and explicit environment binding. Current
+Auth policy permits CLI service-grant issuance to Organization owners/admins. JSON uses contract
+version 1 and does not include credentials. The focused plugin skill is `siteos-seo`.
+
 ## Local state and diagnostics
 
 ```sh
@@ -202,3 +231,39 @@ A report records the revision, runtime, observed Edge location, scenario scope a
 The check covers one route and a bounded observation window, not hidden first-party/server-side
 tracking, every delayed interaction, visual accessibility or legal compliance. Repeat after
 website/publication changes and preserve a separate GTM Tag Assistant check where applicable.
+
+### Forms inbox
+
+Use `siteos forms submissions list --environment <slug> --form <form-id> --json` to search complete
+history. Filters include `--query`, `--status`, `--from`, `--to`, `--limit` (1–100), and `--cursor`.
+The response contains the filtered total and a continuation cursor. Full answers and the saved
+version's labels are available with `siteos forms submissions read --environment <slug> --form
+<form-id> --submission <id> --json`.
+
+`siteos forms submissions status --environment <slug> --form <form-id> --submission <id> --status
+read --expected-status new --json` changes status without overwriting concurrent triage. Statuses
+are `new`, `read`, `archived`, and `spam`. These management commands require the matching Forms inbox
+server release. They use the selected common Project/environment and a scoped Auth grant.
+`forms definition check` compiles the schema locally using the same strict Ajv policy as sync.
+
+### Form archive and deletion
+
+These commands require the lifecycle API on the selected server. Owner/admin rights are required
+for changes; members can list and read. Read a form to obtain its current revision before changing it.
+
+```sh
+siteos forms definition list --environment production --status all --json
+siteos forms definition read --environment production --form <form-id> --json
+siteos forms definition archive --environment production --form <form-id> --expected-revision <revision> --json
+siteos forms definition restore --environment production --form <form-id> --expected-revision <revision> --json
+siteos forms definition delete --environment production --form <form-id> --json
+siteos forms definition delete --environment production --form <form-id> --apply --confirm <form-key> --expected-revision <revision> --expected-submissions <count> --json
+```
+
+Delete without `--apply` only previews the exact Project, Environment, form and submitted-answer
+count. Use the values from that reviewed preview when applying; a stale revision or count conflicts.
+Archive stops new submissions and preserves history. Delete permanently removes versions and
+answers from the working database, retaining only a reserved-key tombstone. That form key cannot be
+reused. Shared Environment credentials remain active for other forms. Sync refuses archived/deleted
+keys and never removes forms missing from a local manifest. Backups follow deployment retention;
+they are not an in-app restore mechanism.