@storystick/cli 0.0.0-stage → 0.2.0-rc.0

package/README.md

@@ -1,3 +1,264 @@
-# Temporary Holding Version
+# @storystick/cli
 
-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.
+The developing [content import interface](CONTENT-IMPORT.md) provides planning,
+bounded native writes, resumable receipts and readback for Main drafts.
+
+The Storystick command-line interface. It compiles Story V1 schemas, connects a
+Next application to a Storystick project, and publishes schema changes through
+the Storystick gateway.
+
+## Commands
+
+```text
+storystick init [project-name] [--link <shortId>] [--team <shortId> | --new-team <name>]
+  [--into <dir>] [--starter <id>] [--origin <url>] --locale <tag>
+  [--site-url <origin>] [--force] [--json]
+storystick generate [--root <dir>] [--output <dir>] [--stories <dirs>]
+  [--check] [--verbose | --quiet] [--json]
+storystick push [--root <dir>] [--stories <dirs>] [--dry-run]
+  [--verbose | --quiet] [--json]
+storystick sync [--root <dir>] [--output <dir>] [--stories <dirs>]
+  [--dry-run] [--verbose | --quiet] [--json]
+storystick login [--gateway-url <origin>] [--hub-url <origin>]
+storystick logout [--local] [--gateway-url <origin>] [--root <dir>]
+storystick whoami [--json] [--gateway-url <origin>] [--root <dir>]
+storystick list [--all] [--json]
+storystick info [shortId] [--root <dir>] [--json]
+storystick connect <shortId> [--root <dir>] [--origin <url>]
+  [--dry-run] [--json]
+storystick archive <shortId> [--yes] [--json]
+storystick migrate preview <module> [--root <dir>] [--run <id>] [--json]
+storystick migrate activate <module> --app-url <candidate-origin>
+  --serving-url <public-origin> [--preview-proof <reference>] [--yes] [--json]
+storystick backfill-refs [--storyType <name> | --document <shortId>]
+  [--dry-run] [--root <dir>] [--verbose | --quiet] [--json]
+storystick slice-previews sync [--root <dir>] [--manifest <file>]
+  [--project <shortId>] [--dry-run] [--verbose | --quiet] [--json]
+storystick mcp --project <shortId> [--root <dir>] [--write]
+```
+
+Run `storystick <command> --help` for the complete option and environment
+contract. `storystick --version` is read from this package's version.
+
+## Project tools for coding assistants
+
+`storystick mcp` serves the native Studio assistant's editorial tools over stdio.
+The default profile allows reads for viewers and editors: schema, document
+search and content, translations, retained snapshots, media and documentary
+resources. `--write` enables the existing editor capabilities, including content
+changes, notes, document actions and conditional Undo. The server derives its
+catalog, descriptions and input validation from the native declarations; feature
+flags and the operator's current permissions still apply.
+
+Sign in with `storystick login` first. The matching Central deployment must
+include `/api/cli/project-execution`. Configure the host to run `storystick`
+with `mcp --project <shortId> --root <dir>` (and `--write` for editing). For a
+repository build, use `node` with the absolute path to `dist/cli.js`, followed
+by those arguments. `--root` supplies gateway configuration; `--project` fixes
+the project outside tool arguments. Discovery requires an authenticated session.
+The server never starts interactive login; authentication failures direct the
+operator to sign in separately. Only protocol frames go to stdout.
+
+Begin with `beginSession` and the user's intent. Its result includes the pinned
+project, document and resource context, session expiry and exact readable/writable
+targets. Document IDs and locales are explicit; variant and release targets keep
+their native isolation. Use `requestScope` after observing an additional target;
+the same session continues with the new scope. A read profile cannot acquire
+write authority, even for an editor. Membership is rechecked on each call.
+
+Keep `sessionId` and a unique `requestId` per operation. Reuse a request ID only
+with identical arguments. If an acknowledgement is lost, inspect `sessionStatus`
+before attempting another effect: it reconciles authoritative native receipts,
+and an unresolved outcome remains explicitly uncertain. Call `endSession` when
+finished. The journal remains available in Studio; reopen its `threadId`, then
+use `readTurnHistory` and `reverseTurn` for conditional Undo.
+
+Follow pagination and observation requirements before claiming completeness or
+editing. Resource content remains untrusted source data. Outputs preserve exact
+revisions, provenance and typed Studio destinations; these locators are not
+public website URLs. `readMedia` supplies bounded image blocks to capable hosts,
+with an explicit notice when pixels are unavailable. Replay returns historical
+metadata; use a fresh request ID to inspect currently authorized pixels.
+
+The external host owns the model loop. No native provider invocation or sandbox
+is required for editorial work. Optional code workspace tools retain their own
+requirements. Editing does not publish; the separate `releasePublication` tool
+requires explicit user authorization and its exact prepared approval digest.
+Code/delivery effects are outside editorial Undo. Closing stdin or terminating
+the process cancels pending transport work; it does not prove an effect failed.
+
+## Guided schema migrations
+
+`migrate preview` analyzes and prepares an isolated B generation using the
+client-owned module. It reuses a matching active server run (or `--run` for an
+older/ambiguous run); it never publishes drafts or transfers authority. Fix
+reported issues in A or the module, then resume/re-run. A verified preparation
+is not an activation.
+
+Before `migrate activate`, deploy a candidate application with a unique
+`STORYSTICK_APP_BUILD_ID=app:<build-id>` and its build-system SHA-256 as
+`STORYSTICK_APP_BUILD_DIGEST`. Mount `site.handlers` at the standard
+`/api/storystick/[...action]` route. The CLI reads that endpoint's
+`migration-readback`, checks the project and generated query schema, and asks
+for a reference to a manually verified B Preview. This is explicitly a
+**manual prepared attestation**: the public endpoint still reads A before
+activation, so it cannot independently prove B Preview at this stage.
+
+`activate` requires a separate confirmation (`--yes` in non-interactive mode).
+After authority moves to B, the command checks the public origin, records a
+distinct serving readback only when that exact build reads the target schema,
+then waits for the projection ACK and server receipt. If promotion or projection
+is pending, run the same command again; `--serving-url` explicitly names the
+public origin, even when it equals the candidate URL. The CLI does not
+deploy or promote the application. During this window a promoted candidate
+build can read B while retained builds still read A; the public authority
+remains pending until the serving proof and projection ACK. `status`, `issues`, `resume`, `attest` and
+the original three-identifier `activate` form remain available for recovery.
+
+## Slice Library captures
+
+Repository-managed captures stay outside `.story` files. Declare the explicit
+base/variation mapping in `slice-previews.json`:
+
+```json
+{
+  "version": 1,
+  "previews": [
+    { "slice": "hero", "file": "captures/hero/base.png" },
+    {
+      "slice": "hero",
+      "variation": "centered",
+      "file": "captures/hero/centered.png"
+    }
+  ]
+}
+```
+
+Run `storystick slice-previews sync`. The agent-friendly
+`--dry-run --json` form validates the complete mapping without network or
+storage effects. Every referenced file must remain inside the project root,
+including after symlink resolution.
+
+## Schema workflow
+
+`generate` resolves `.story` files and atomically publishes one immutable local
+generation. `--check` compares the expected bytes without modifying the
+filesystem.
+
+`push` asks the server for a change plan before publishing. Initial, additive,
+presentation-only, and unchanged plans are accepted. Breaking or unknown
+changes are refused; V1 deliberately has no generic `--force` or universal
+migration engine. `push --dry-run` returns the server plan without creating a
+schema row or outbox event.
+
+`sync` combines both operations without lying about their order: it stages the
+generated bytes, publishes the same schema version, and only then moves the
+local generation pointer. If the process stops after a confirmed push, the next
+identical `sync` completes the local commit from
+`.storystick/sync-operation.json` without contacting the server again.
+`sync --dry-run` writes neither staged artifacts nor remote schema state.
+
+## Init, link, and connect
+
+`init` selects an external starter from the Storystick catalog. Catalog entries
+pin an immutable HTTPS archive with its SHA-256 digest and content-tree digest;
+the CLI verifies both before exposing its files in the target directory. No
+GitHub account or GitHub credential is required. The V2 catalogue and archives
+must be hosted before this local candidate can support public onboarding.
+`minimal-next` is the default reference starter, not a limit on the catalog:
+blog, event, landing-page, or third-party maintained starters can coexist as
+separate immutable entries. `STORYSTICK_STARTER_CATALOG_URL` can point to an
+alternate HTTPS catalog.
+
+For an existing Next App Router project, use `--into .`. The CLI applies the
+same Next integration kernel and the starter's declared content overlay. It
+preserves customer files and fails with an explicit conflict unless `--force`
+authorizes replacement. Starter verification and Story preparation happen
+before authentication, project creation, or secret writes.
+
+For Next integrations, missing `@storystick/next` and `@storystick/cli`
+dependencies use the versions declared in the verified starter's `package.json`.
+Existing application declarations are preserved. The starter must declare both
+versions as non-empty strings; an incomplete or invalid contract is refused
+during planning, before application files are written.
+
+`--locale` records the site's canonical BCP 47 primary locale and creates new
+projects as explicit monolingual projects. `--site-url` records the production
+origin used by canonical URLs, `hreflang`, and sitemaps. It may be omitted
+during local onboarding, but a production build fails until it is configured.
+
+Create and link flows are resumable through the secret-free
+`.storystick/init-operation.json` receipt. The four connection values are
+validated and committed to `.env.local` as one atomic unit:
+
+```text
+STORYSTICK_PROJECT_ID
+NEXT_PUBLIC_STORYSTICK_PROJECT_ID
+STORYSTICK_API_KEY
+NEXT_PUBLIC_STORYSTICK_PUBLISHABLE_KEY
+```
+
+`connect` replaces that complete unit for an existing application; it never
+switches only the project ID. `--dry-run` redacts both keys.
+
+## Authentication and automation
+
+`login` uses an explicit browser device flow. CLI sessions have a fixed server
+lifetime and are revocable with `logout`; `logout --local` only forgets the
+selected local credential. Sessions are stored separately for each canonical
+gateway issuer. `logout` and `whoami` accept `--gateway-url` and `--root` to
+select that environment. Credentials without an issuer are refused and require
+an explicit new login. A nonstandard gateway selected through project/env
+configuration cannot start a device flow automatically: run `storystick login
+--gateway-url <origin>` explicitly. The prompt shows the recipient gateway before
+the verification URL and code. This destination binding is distinct from the JWT
+issuer claim. A remote logout succeeds only after `{ revoked: true }`;
+a network error, redirect, HTTP 401 or missing receipt preserves the local session.
+Runtime URLs require HTTPS, except HTTP on localhost/127.0.0.1/[::1]. JSON and non-interactive commands never start a prompt or
+device flow implicitly.
+
+Short commands emit one JSON envelope on stdout:
+
+```json
+{ "ok": true, "command": "push", "version": "1", "data": {}, "diagnostics": [] }
+```
+
+`backfill-refs --json` is the sole streaming exception: it emits JSONL progress
+records followed by one final record. Status text uses stderr. Failures are
+non-zero, SIGINT exits 130, and credentials are redacted from output and
+receipts.
+
+Optional runtime overrides are `STORYSTICK_HUB_URL` and
+`STORYSTICK_GATEWAY_URL`. `STORYSTICK_NO_BROWSER=1` disables automatic browser
+opening during explicit login.
+
+## Development
+
+```bash
+pnpm --filter @storystick/cli run test
+pnpm --filter @storystick/cli run build
+```
+
+The build cleans `dist/` before compiling so removed commands cannot remain in
+the package. `pnpm starter:qualify` packs every SDK dependency and the CLI,
+installs the reference starter outside the workspace, then runs generation,
+typecheck, and a production Next build. `ci:packages` runs that qualification
+after auditing every publishable tarball.
+
+Licensed under FSL-1.1-MIT (see `LICENSE`).
+
+Project creation always asks which team should own the project, including when
+only one team exists. Choose an existing team or create a new one. Headless
+creation requires `--team` or `--new-team`. Team and project creation share the
+bootstrap operation, so resuming a lost response does not create duplicates.
+
+`init` completes after the pushed schema's persisted checkpoint is readable
+through the Content Plane. An unavailable projection produces a resumable partial
+result after a bounded wait, preserving the local connection and remote project.
+The minimal starter contains schemas and components, not published pages.
+
+## Candidate distribution contract
+
+See [PUBLIC-API.md](./PUBLIC-API.md) for supported entries, reserved SDK contracts,
+the qualified runtime matrix and the candidate cohort. Upgrade Storystick
+packages together.

package/assets/next-v1/app/[[...pathname]]/error.tsx

@@ -0,0 +1,10 @@
+'use client'
+
+export default function ErrorPage({ error, reset }: { error: Error & { digest?: string }; reset(): void }) {
+  return <main>
+    <h1>Something went wrong</h1>
+    {process.env.NODE_ENV !== 'production' ? <pre>{error.message}</pre> : null}
+    {error.digest ? <p>Reference: {error.digest}</p> : null}
+    <button onClick={reset}>Try again</button>
+  </main>
+}

package/assets/next-v1/app/[[...pathname]]/not-found.tsx

@@ -0,0 +1,8 @@
+export default function NotFound() {
+  return (
+    <main className="status-page">
+      <p>404</p>
+      <h1>Page not found</h1>
+    </main>
+  )
+}

package/assets/next-v1/app/[[...pathname]]/page.tsx

@@ -0,0 +1,38 @@
+import { notFound, redirect, permanentRedirect } from 'next/navigation'
+import { SliceZone } from '@storystick/next'
+import { components } from '../../components/slices'
+import { site } from '../../lib/site'
+
+type PageProps = {
+  params: Promise<{ pathname?: string[] }>
+  searchParams: Promise<Record<string, string | string[] | undefined>>
+}
+
+export default async function Page(props: PageProps) {
+  const route = await site.resolvePage(props)
+  if (route.type === 'redirect') {
+    const navigate = route.permanent ? permanentRedirect : redirect
+    navigate(route.redirectTo)
+  }
+  if (route.type !== 'document') notFound()
+  const document = route.document
+  return <main>
+    <SliceZone
+      slices={document.fields[{{SLICES_FIELD}}]}
+      components={components}
+      fallback={() => <p className="slice-error">This section is temporarily unavailable.</p>}
+    />
+  </main>
+}
+
+export async function generateMetadata(props: PageProps) {
+  const route = await site.resolvePage(props)
+  if (route.type !== 'document') return site.metadata(route)
+  const fields = route.document.fields
+  return site.metadata(route, {
+    title: fields[{{TITLE_FIELD}}],
+    description: fields[{{DESCRIPTION_FIELD}}],
+  })
+}
+
+export const dynamic = 'force-dynamic'

package/assets/next-v1/app/api/storystick/[...action]/route.ts

@@ -0,0 +1,4 @@
+import { site } from '../../../../lib/site'
+
+export const GET = site.handlers.GET
+export const POST = site.handlers.POST

package/assets/next-v1/app/layout.tsx

@@ -0,0 +1,28 @@
+import { previewTextProps, Storystick } from '@storystick/next'
+import Link from 'next/link'
+import { site } from '../lib/site'
+import './globals.css'
+
+// The shared header also reads live CMS data on built-in routes such as 404.
+export const dynamic = 'force-dynamic'
+
+async function Header() {
+  const client = await site.client()
+  const settings = await client.query({{SITE_SETTINGS_STORY}}).select({ {{SITE_NAME_FIELD}}: true }).fetch()
+  if (!settings) return null
+  return <header className="site-header">
+    <Link href="/" className="site-name" {...previewTextProps(settings.fields.{{SITE_NAME_FIELD}})} />
+  </header>
+}
+
+export default async function RootLayout({ children }: { children: React.ReactNode }) {
+  return <html lang={await site.locale()}>
+    <body>
+
+        <Header />
+        {children}
+        <Storystick />
+
+    </body>
+  </html>
+}

package/assets/next-v1/app/sitemap.ts

@@ -0,0 +1,3 @@
+import { site } from '../lib/site'
+export const dynamic = 'force-dynamic'
+export default async function sitemap() { return site.sitemap() }

package/assets/next-v1/env.local.example

@@ -0,0 +1,13 @@
+STORYSTICK_PROJECT_ID=
+STORYSTICK_API_KEY=
+NEXT_PUBLIC_STORYSTICK_PROJECT_ID=
+NEXT_PUBLIC_STORYSTICK_PUBLISHABLE_KEY=
+
+# Required for <html lang>, including synthetic monolingual projects.
+# Required in production for canonical URLs, hreflang and the sitemap.
+STORYSTICK_SITE_URL=
+
+# Optional: required only for signed publish webhooks.
+STORYSTICK_WEBHOOK_SECRET=
+
+NEXT_PUBLIC_STORYSTICK_GATEWAY_SYNC_URL=

package/assets/next-v1/globals.css

@@ -0,0 +1,17 @@
+*,
+*::before,
+*::after {
+  box-sizing: border-box;
+}
+
+body {
+  margin: 0;
+  color: #111;
+  background: #fff;
+  font-family:
+    system-ui,
+    -apple-system,
+    BlinkMacSystemFont,
+    'Segoe UI',
+    sans-serif;
+}

package/assets/next-v1/lib/site.ts

@@ -0,0 +1,10 @@
+import { createSite } from '@storystick/next/server'
+import * as definition from '#storystick/query'
+
+const siteUrl = process.env.STORYSTICK_SITE_URL
+if (!siteUrl) throw new Error('STORYSTICK_SITE_URL is required for canonical metadata and sitemap.')
+
+export const site = createSite({
+  definition,
+  siteUrl,
+})

package/assets/next-v1/next.config.ts

@@ -0,0 +1,4 @@
+import type { NextConfig } from 'next'
+
+const nextConfig: NextConfig = {}
+export default nextConfig

package/assets/skills/storystick-development/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: storystick-development
+description: Develop a Storystick site's sections, story schema and Next.js rendering together. Use when configuring a project, connecting source or hosting, adding or adapting a slice, changing a .story file, generating bindings, or working on code inside a Storystick release.
+---
+
+# Storystick development
+
+Read the repository's `AGENTS.md` / `CLAUDE.md`, package scripts, the closest
+existing section and its `.story` definition first. The repository's design
+system and reusable fragments are the starting point. Do not invent a second
+agent, CMS, routing layer or SDK API to complete a section.
+
+## Configure a project
+
+Run `storystick setup --json` first. It inspects the checkout without executing
+scripts or changing remote state. Read `storystick guide --reference setup` for
+local, starter and GitHub paths, source transfer and hosting configuration.
+Reuse a connected project; setup is not a reason to create another project.
+
+## Find the existing grammar
+
+Use ordinary terminal tools (`rg`, file reads, package scripts). Search the whole
+repository when needed. A file catalogue is orientation, not an editing boundary.
+Use `grep` / `find` when `rg` is unavailable. Invoke the project's installed CLI
+through its package runner (for example `pnpm exec storystick guide`) rather than
+assuming a global binary. `cwd` is relative to the repository root; paths in the
+command are relative to that working directory.
+Find the page's composition field, its permitted slices, the component registry,
+and generated bindings. A component existing on disk does not make it available
+in the editor: its story must be included in the page's composition grammar and
+that grammar must be synchronized to the selected release.
+
+Prefer existing slices. If none expresses the intended content well, inspect a
+Storystick UI Library reference, then adapt its content model and presentation
+to this repository. Reuse fragments and existing document references. Do not copy
+example data, add an alternate design system or silently create a submission
+backend for a visual contact form.
+
+## Work in the selected release
+
+The workspace supplies `STORYSTICK_RELEASE_ID` and a short-lived CLI session.
+`storystick push` / `storystick sync` use that release automatically. Outside a
+workspace, use `storystick release list --project <id>`, then
+`storystick release use <id> --project <id>`; `--release <id>` is also explicit.
+`storystick release create <name>` creates a draft. Inspect `--help` and existing
+scripts for root, story directories and generation output. Do not change the
+workspace's supplied destination or credentials.
+
+Studio and MCP use the same release, schema and content tools and the same
+domain writers. MCP session context reports the CLI selection as
+`cliReleaseContext`; `sessionStatus` refreshes it. This is the destination used
+by CLI schema commands, not an implicit change to a document's write scope.
+Choose the matching `releaseId` for schema reads and new content, and acquire
+the exact release document scope before editing existing content. Main remains
+an explicit choice for independent work. Code and schema preparation do not
+silently move unrelated content into a release.
+
+`generate` produces local bindings. `sync` generates and admits the matching
+schema in the selected release; `push` admits the schema without generation.
+Inspect an admission failure and change the actual cause before retrying. Do not
+retry an unchanged rejected schema or refetch a library reference already read.
+A schema admission is not publication. Publication and scheduling are outside
+this workflow. Existing content remains available in Main until publication.
+
+## Complete the change
+
+Edit the story, component and registry as one coherent change. Run the project's
+relevant checks; use their diagnostics to repair the implementation. A form that
+has no configured submission destination must say so in the result.
+
+The terminal saves source changes after each command, including failed commands.
+Git ignored dependencies and build caches are not durable source. Keep authored
+assets in tracked/non-ignored paths. Do not print credentials or put them in files.
+The dev preview updates from the working source; ordinary styling edits do not
+need a new sandbox. Report separately what was saved, checked, admitted and seen
+in preview. If a check failed, report that evidence instead of claiming success.
+
+Read `references/story-and-next.md` (`storystick guide --reference story-and-next`) for the boundary between stories, generated
+bindings and the existing Next.js API.

package/assets/skills/storystick-development/references/setup.md

@@ -0,0 +1,152 @@
+# Connect a Storystick project
+
+Keep one project identity while adding capabilities. Content editing does not
+require a source upload or hosting connection. A local Vercel link is not a
+Storystick connection and does not authorize publishing.
+
+## Inspect before changing
+
+Run `storystick setup --json` in the application directory. It reads local facts
+without executing package scripts. `setup --remote --json` adds the project's
+current schema, source and hosting facts through your CLI login. Use `--help`
+for options. Authentication requiring human consent is explicit: run
+`storystick login`, never print or request credentials in a chat.
+
+If connected, reuse that short ID. Otherwise choose:
+- Existing code: `storystick connect <shortId> --dry-run --json`, then repeat
+  without `--dry-run` after reviewing the target. Use `init` to create a project
+  only when one does not already exist.
+- New site for a Studio project: `storystick init --link <shortId> --starter
+  minimal-next --into ./website --locale <tag> --json`. Supply the intended
+  locale explicitly in agent/noninteractive runs; never infer it from the
+  machine locale. Keep the initializer's receipt and use its
+  reported resume command after interruption. Do not start another initialization.
+
+Read repository instructions and existing generation/sync scripts. Connecting
+credentials does not upload the schema; the repository's `sync` or `push` does.
+
+## Add Studio code editing
+
+For a single Next.js application at the Git root with npm or pnpm:
+1. Export its schema locally with `storystick schema --json`. This validates but
+   does not admit the schema or change any remote content.
+2. `storystick source configure --schema generated/storystick-schema.json --json`
+   creates `.storystick/source.json`. Inspect its install, generation, check and
+   preview commands. The preset requires the CLI installed in the application.
+3. Commit the intended source with ordinary Git. `source prepare --dry-run --json`
+   lists the exact committed paths and revision to be transferred. Dirty files
+   are not included. Check that the schema version and source commit agree.
+4. `storystick source prepare --json` transfers that commit. It does not publish.
+   `setup --remote --json` reads back the prepared source. Workspace access may
+   still need enabling by the Storystick operator.
+
+Monorepos and custom frameworks use `source configure --config <proposal.json>`.
+Include the application **and its workspace dependencies**, lockfile and package
+configuration. Set command `cwd` explicitly where required. Consult
+`source configure --help`; derive commands from the repository, not a guessed
+folder layout. Existing configuration is never overwritten automatically.
+
+A proposal uses the same recipe as remote execution. For example, adapt this
+shape to the actual monorepo; these paths and scripts are illustrative:
+
+```json
+{
+  "scope": {
+    "appRoot": "apps/website",
+    "include": ["apps/website", "packages/ui", "package.json", "pnpm-lock.yaml", "pnpm-workspace.yaml"],
+    "exclude": ["node_modules", "apps/website/.next", "apps/website/generated"]
+  },
+  "schemaVersion": "<version from the locally exported schema>",
+  "recipe": {
+    "install": [
+      { "argv": ["pnpm", "install", "--frozen-lockfile"] },
+      { "argv": ["pnpm", "exec", "storystick", "generate"], "cwd": "apps/website" }
+    ],
+    "checks": [
+      { "name": "schema", "argv": ["pnpm", "exec", "storystick", "schema"], "cwd": "apps/website" },
+      { "name": "build", "argv": ["pnpm", "run", "build"], "cwd": "apps/website" }
+    ],
+    "schemaCheck": "schema",
+    "schemaOutput": "apps/website/generated/storystick-schema.json",
+    "preview": { "argv": ["pnpm", "run", "dev", "--hostname", "0.0.0.0", "--port", "3000"], "cwd": "apps/website", "port": 3000 },
+    "allowedHosts": []
+  }
+}
+```
+
+Command directories and `schemaOutput` are relative to the repository root.
+Include the full transitive workspace dependency closure, not just `packages/ui`.
+Keep credentials in the project's protected environment, not command arguments
+or this proposal. Configure from the Git root with `--root` when necessary.
+
+## Return source changes
+
+Use `source status <workspaceId>` before exporting. `source export` requires its
+current revision and a new output directory. `source apply --change <directory>
+--out <new-checkout>` performs a three-way merge and preserves the original local
+checkout. Resolve conflicts and review before merging into your own branch.
+Use `source import` only with the reviewed commit and current workspace revision.
+
+GitHub is optional. A connected GitHub App supports `source github-status`,
+`github-inspect`, `github-prepare`, `github-import` and `propose`.
+`source github-inspect --project <id> --json` reads metadata at an immutable commit
+without executing package scripts. Use `--app-root <folder>` for a monorepo and
+`--ref <commit>` to keep that same commit while reviewing application folders.
+Use `--config <proposal.json>` to check an edited scope and recipe against that
+same commit before preparation; use its matching `--app-root` for a monorepo.
+The result includes the proposed configuration, issues, existing prepared base
+and `connectionRevision`. Save the reviewed configuration as a local JSON file,
+then pass that file to `source github-prepare --config <file> --ref <commit>
+--connection-revision <revision> --project <id> --json`. A changed/revoked
+connection or a different prepared base is refused. Studio Project setup uses
+these same inspection and preparation operations; neither starts a workspace
+nor publishes a release.
+`propose` opens a draft PR; configured CI may run. Adding GitHub later must retain
+the same project and a verifiable common source base. If the histories differ,
+reconcile them first; do not overwrite the workspace or invent a new project.
+
+## Connect a provider account
+
+`storystick connection status --json` reports the same connections as Project
+setup in the Studio. For GitHub or Vercel, `connection begin --provider <provider>
+--json` returns an attempt ID and an authorization URL. The account holder opens
+that URL and authorizes access; an agent must not invent authorization or ask for
+the account's password/token. Return to `connection status` after confirmation.
+
+For an authorized attempt, `connection resources --attempt <id> --json` lists
+accessible targets. For GitHub, first choose an installation, then list its
+repositories with `--installation <id>`. Follow the returned pagination cursor
+with `--cursor` when needed. Use the exact IDs returned by the provider:
+
+- GitHub: `connection select --provider github --attempt <id> --installation
+  <id> --repository <id> --full-name <owner/repository> --branch <branch> --json`.
+- Vercel: `connection select --provider vercel --attempt <id> --destination
+  <projectId> --json`.
+
+Use `--project <shortId>` outside a connected checkout. Selecting a target does
+not transfer source, create a repository, configure build commands, or deploy.
+Continue with the existing source/delivery operations. An expired attempt needs
+a new `begin`; do not create another Storystick project. If provider registration
+is unavailable on this installation, local source transfer remains independent.
+
+## Add release deployment separately
+
+Use `delivery status --json` to inspect current configuration. For an existing
+Vercel project, `delivery configure --from-vercel --site-url https://example.com
+--dry-run --json` reads IDs from `.vercel/project.json` and previews the proposal.
+Without a local link use `--team <teamId> --destination <projectId>`. Review root
+and build overrides, then repeat without `--dry-run`. Readback confirms saving.
+`delivery verify --json` checks account/project/domain access without deploying.
+It does not prove build success or write permission.
+
+Connected customer grants are resolved on the server, never in source or command
+arguments. A disconnected/revoked grant must be reauthorized; it never falls back
+to the operator's credentials. Existing operator pilot configuration is used only when
+no customer connection record exists. The current setup screen supports Vercel. Other
+hosting workflows can keep serving the site and editorial revalidation; do not
+claim that an unwired provider supports coordinated code publication.
+
+Storystick owns coordinated release publication. If Git already auto-promotes
+production deployments, settle that trigger with the builder before enabling a
+second publisher. A source push, a preview and production activation are distinct.
+Content-only releases keep their existing revalidation path.