@universalcms/connect 0.0.0-stage → 0.13.0

package/README.md

@@ -1,3 +1,780 @@
-# Temporary Holding Version
+# @universalcms/connect
 
-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.
+Local, deterministic website setup without AI. Universal CMS stays hosted; this
+package creates a website integration, not a CMS installation. Version 0.13.0 is
+prepared locally; this repository does not establish its public npm availability.
+
+## Quick start
+
+```sh
+npx @universalcms/connect@latest --cms https://YOUR_CMS_ADMIN_ORIGIN
+```
+
+Run it in the website folder. It opens the CMS to approve the website, installs
+this package, connects pages, header/footer and settings, saves the website key
+privately in `.env.local`, then guides the restart, content import and final check.
+Run it again to continue where it stopped. Without a browser, create a one-time
+`--code` command in Developer setup. See [connector setup](../../docs/connector-setup.md#one-command-connection-recommended).
+The individual commands below remain for developers and reviewed integrations.
+
+Supported templates: **Next.js 16 App Router on Node**, **React 19.2+ with
+Vite 6/7/8 plus a private Node server**, and **bounded Astro 7.2.1–7.x projects
+with official Node 11/React 7 integrations and React/React DOM 19.2+ within 19.x**.
+Version 0.12.0 also supplies bounded native Vue, Nuxt, Angular, SvelteKit and
+literal HTML adapters. The same CMS download service supplies a separate native
+[WordPress PHP plugin](../wordpress/README.md), installed with WP-CLI, not npm.
+Use Node 22.12 or newer (below 27); individual frameworks have stricter floors.
+Stable exact, caret and tilde version declarations are recognized. Workspaces,
+Pages Router, static Next exports, dynamic routing configuration,
+custom page extensions/base paths and ambiguous framework evidence require manual
+review. Standard Cache Components layouts support source export and original-page
+publication checks. Route groups support source discovery and publication checks. Analyze the individual
+website folder, not its parent workspace.
+
+| Selection | Automatic profile in 0.12.0 |
+| --- | --- |
+| Vue | Vue 3.5, Vite 7/8, official Vue plugin 6; literal root SFC and ordinary startup. Vue must be a production dependency. Generated private Node SSR host. |
+| Nuxt | Nuxt 4 and Vue 3.5, literal `app/pages`, ordinary server configuration; Node 22.18+, 24.11+ or supported newer major below 27. |
+| Angular | Angular 22.2, TypeScript 6, existing ordinary Node SSR scaffold and literal root component; Node 22.22.3+, 24.15+ or 26. A browser-only scaffold needs the matching official Angular SSR integration first. |
+| SvelteKit | Kit 3.1+, Svelte 5.57.1+, Vite 8.0.12+, Vite plugin 7.3.1+, adapter-node 6; Node 22.17+ or supported newer major. Literal pages and ordinary Kit 3 Vite configuration. |
+| Static | Complete literal `index.html` documents at directory routes, plus ordinary CSS/images/fonts. A generated private Node host is required. Custom scripts/builders and static-only deployment require review. |
+| WordPress | Separate native plugin for inspected single-site WordPress pages/posts; see its exact theme, PHP, permalink and migration restrictions. |
+| Custom | Inspect the actual project and dispatch to a compatible implemented adapter. An arbitrary backend or custom router still needs a reviewed integration. |
+
+The native adapters preserve supported framework markup and styles, freeze the
+original source privately, and bind current published blocks to stable IDs. A
+self-contained `<universalcms-website>` element hosts the shared twelve-section
+configuration renderer while the framework retains its native light DOM. Vue,
+Nuxt, Angular, SvelteKit and HTML customers do not install React. Node frameworks
+use the same source, publication, document, settings and new-page contracts.
+Version 0.12 adds explicit native route and layout reviews described below.
+Executable page logic, unsupported custom routers/layouts and ownership conflicts
+still require a reviewed adapter; the CLI never deletes them to pass.
+Angular's generated development command builds and runs the reviewed SSR server;
+it does not promise `ng serve` hot reload.
+
+Follow Developer setup in order: install the connector, run the fully scoped
+read-only `preflight` command, then create or reuse an environment-scoped server
+key and save it privately only after preflight succeeds. Run the fully scoped
+`setup --original-routes-only` command in the website folder. Full setup prepares
+source import, original-route publication control and native CMS content bindings,
+then requires a second file review to install all twelve website configuration
+consumers. `setup-settings --apply` resumes that stage if it was not completed.
+Restart/deploy, verify the running website and import drafts. Imported drafts are
+unavailable on the managed original URLs until explicitly published in the CMS.
+Saving a draft edit of an already-published page preserves its last publication;
+unpublishing removes the page. Failed delivery never restores hardcoded copy.
+
+## Incomplete setup and custom layouts in 0.12
+
+A failed preflight or installer does not install the missing endpoint. Developer
+Setup keeps later commands behind the preflight acknowledgment, reports the
+failed stage, and separates **Diagnose connection** (read-only) from **Repair
+incomplete setup** (explicit website code changes). Neither changes CMS content,
+credentials, permissions or publications. The generated AI repair instructions
+use the same installed framework-specific review commands as the CLI.
+
+For a fresh Next 16 App Router project, `review-routes --dry-run` inventories
+ordinary static routes and supported final single-segment dynamic routes.
+`review-routes` asks which routes stay native and saves their dependency hashes
+only after confirmation. At least one public page must remain CMS-managed.
+`review-layout --dry-run` inspects one ordinary server root layout with a single
+children slot and one unconditional semantic header/footer. Inline markup and
+supported local default/named components are recognized. After review, full setup
+appends settings consumers while preserving native controls and route ownership.
+
+For supported Vue, Nuxt, Angular SSR, SvelteKit and Static profiles,
+`review-layout` proposes seven empty settings slots inside literal native
+header/footer markup and saves the reviewed source hashes. Existing text, links,
+classes and native details controls remain website-owned. Forms, executable
+expressions and component-driven chrome require a native adapter. New CMS-only
+pages keep the shared CMS page layout; they do not clone an original native
+page. Astro custom chrome remains a separately reviewed integration.
+
+Both review commands default to No, support `--dry-run`, reject linked/stale
+source and refuse to rewrite an already-installed content integration. A review
+is not installation or verification. Rerun scoped preflight, complete setup,
+restart/deploy, then check source/publication/settings and actual website
+behavior. Arbitrary custom routes and every possible framework version are not
+automatically supported.
+
+After successful import, run `universalcms-connect finalize-source --apply` and
+restart/deploy to close the bootstrap source endpoint. Then run
+`universalcms-connect check-publication --path /` and verify actual rendered
+content in a browser. Both CLI and AI-assisted setup follow this same contract.
+A local connection does not verify a separate live deployment.
+
+Version 0.10.0 adds original-page Astro setup through the same CLI and AI contract.
+The reviewed installation adds the official Node and React integrations; it does
+not silently upgrade Astro. Public literal `.astro` pages and simple relative
+layouts keep their native markup/classes/styles, while a shared React island
+composes all twelve settings consumers and additional published blocks. The
+generated on-demand Node runtime serves source, publication and settings
+endpoints and new published CMS paths. Use the generated scripts to restart, or
+`npm run build` and `npm run start` to deploy, then verify actual delivery and
+rendering. This integration requires a Node host; static-only hosting uses a
+separately reviewed private content build.
+
+Astro inspection refuses executable frontmatter, arbitrary components, dynamic
+or private routes, middleware, native custom chrome and ambiguous ownership.
+Document-base/HTTP-equivalent metadata and public HTML, extensionless pages,
+reserved/private assets or linked files also require review. Static assets are
+checked because the standalone server serves them before publication middleware.
+Supported headings, paragraphs, simple text lists and quoted images get stable
+bindings; standalone safe links remain native. Root-relative images resolve
+against the saved website origin. Formatted list rows and links inside editable
+text need explicit bindings. Source files, original baselines, imported layouts
+and inventories are checked before changes. The source/generated-file and
+aggregate snapshot cap is 128 KiB; route, AST and document budgets also apply.
+See the [Astro adapter guide](../astro/README.md) for exact limits and sequence.
+Installing all twelve consumers grants no settings access: current server-key
+sections, saved configuration, enabled state and consent still control output.
+Generated lifecycle hooks run `sync-source` before development, build, start and
+preview; custom existing hooks are preserved and require review. Use the generated
+package scripts. Direct Astro commands bypass ownership validation and are outside
+the supported setup workflow.
+
+Version 0.9.3 introduced local `preflight` before key entry in CLI and AI-assisted
+instructions. It checks actual framework/runtime evidence and plans original
+source, publication and content bindings without writing files, reading private
+environment files or executing project code. A passing plan is not an installed
+or verified live connection. Stop on a review-required result and follow its
+framework-specific guidance. Native framework support added in 0.12.0 uses the
+profiles above. Other backends and incompatible versions retain the applicable
+reviewed private SDK, native REST or build integration.
+See the [framework support matrix](../../docs/connector-setup.md#framework-selection-and-preflight).
+
+Stop when any setup command fails. Saving the private key alone does not install
+the source, publication or settings endpoints. If setup refuses a native route or
+custom layout, preserve it and complete its reviewed integration before the
+restart/check steps; restarting does not create missing endpoint files.
+
+Version 0.9.2 supports explicit reviewed native ownership for mixed Next
+application/content sites through `.universalcms/native.routes.json`. The manifest
+records the `reviewed-next-native-v1` profile, exact native static paths, final
+single-segment patterns such as `/shop/[id]`, and reviewed source-file hashes.
+Native application routes stay out of the source import and retain their own
+rendering. A developer must review this manifest; automatic detection never
+silently labels a product, cart or prescription workflow as CMS-owned content.
+Unsupported dynamic descendants, changed hashes and overlapping ownership stop
+setup. Custom headers and footers still need explicit shared settings components.
+
+Full setup also checks the running publication adapter after saving. If it prints
+`CONNECTION NOT READY`, follow its exact-origin restart/deployment instructions
+and scoped `check-publication` command. An old server can continue running after
+integration files were removed or packages reinstalled. Setup never stops it or
+switches ports automatically; saved files alone do not mean a connected website.
+
+Run these commands in the project that serves the website URL shown in Developer
+setup. A different website folder keeps its own connection and key. If the CLI
+reports a connection mismatch, compare its saved and requested public values,
+then open the correct project folder or copy commands for the existing website.
+Do not continue to restart/check steps after that failure, remove scope guards,
+or reuse another website's key. A busy port can mean the correct website is
+already running; stop only its known server before restarting it.
+
+The website URL must identify the customer website, not the CMS admin. CLI and
+AI setup use the same public source reader; neither setup method can fetch a
+customer export from the centrally hosted admin's origin.
+
+### Website configuration and new published routes (0.9.1)
+
+Full `setup` includes a separate mandatory review of all twelve website settings
+consumers after original-page integration. Both CLI and AI-assisted setup require
+those consumers to be installed; installing only content or Navigation leaves
+full setup incomplete. Declining or failing the review also leaves setup
+incomplete. To complete that stage or review an intact supported installation,
+use the saved public connection:
+
+```sh
+npx --no-install universalcms-connect setup-settings --apply
+npx --no-install universalcms-connect check-settings
+```
+
+Restart or deploy between those commands. The first installs shared consumers
+for branding, social, SEO, languages, analytics, navigation, experience, scripts,
+redirects, authors, templates and taxonomies. It also resolves new published CMS
+page/post destinations and taxonomy archives without adding every entry to the
+menus. Original website links remain; saved CMS menu additions are separate.
+It changes no CMS records, publications, keys or granted configuration sections.
+
+Automatic installation supports intact generated Next.js App Router, simple
+Vite original-page wrappers and bounded Astro layouts without existing site
+chrome. The exact reviewed
+commerce profile also installs all twelve consumers, placing saved menu additions
+inside its native desktop header, mobile menu and footer while preserving native
+links, cart behavior and reserved commerce routes. Its shared layout supplies
+branding, social, languages and consent controls, with the remaining settings
+bound to the server runtime and managed pages. Other native headers/footers,
+custom wrappers and ambiguous routers require a reviewed adapter. The planner
+refuses to overwrite them. Reuse `@universalcms/connect/website-runtime`,
+`@universalcms/connect/react-website` and `@universalcms/connect/website.css`, placing
+the explicit components in the website's existing layout. No arbitrary website
+or framework support is implied by a successful package installation.
+
+The settings diagnostic is a credential-free, exact-origin, no-store read at
+`/api/universalcms/settings?check=connection&siteId=...&environmentId=...`.
+It returns all twelve consumer-installation/read statuses and `renderedVerified: false`, never
+setting values or secrets. `installed: false` means the website lacks that
+consumer; full setup and `check-settings` cannot pass the installation gate until
+all twelve are installed. For an installed consumer, an authorized unsaved
+section is `missing`; an ungranted section is `denied`; a delivery error is
+`unavailable`. A key intentionally
+granted only SEO and Scripts can leave the other ten sections disabled while
+their installed consumers remain ready for a later authorized key. Passing the
+installation gate does not mean those disabled features are working. Neither the
+CLI nor the admin broadens access or changes a key automatically.
+Test the actual required output, script/analytics consent, redirect status,
+metadata, menu clicks, empty settings and refresh independently for each deployed
+origin. HTTP delivery success is not rendered-behavior verification.
+
+For a reviewed custom layout, put one `WebsiteProvider` around the existing
+layout and place `CmsNavigation` in the native desktop header, mobile menu and
+footer. Pass `excludeUrls` for links already rendered by that native menu;
+`location="footer"` includes saved flat links, groups and footer text. A mobile
+slot can use `onNavigate` to close its existing menu. Use
+`CmsWebsitePage chrome={false}` for new CMS page bodies inside that layout.
+Preserve native interaction handlers and route families. Do not install a second
+`CmsWebsite` header/footer around a layout that already owns them. A Navigation-only
+adapter is incomplete: compose branding, social and language controls, experience
+and consent controls, current SEO and redirects, consent-gated analytics/scripts,
+and author/template/taxonomy presentation for managed pages. Keep one settings
+and script-effects owner per website scope. Validate all twelve consumers, the
+server adapter, publication filtering, exact origin and actual desktop/mobile
+link clicks before reporting the layout connected. Instructions and diagnostics
+never contain or replace the private key.
+
+The generated settings manifest records owned adapter files. Subsequent key
+renewal and source finalization accept those intact owned adapters. For an
+expired key, save a replacement with the intended same sections using
+`server-key --prepare-only`, then restart/deploy and verify delivery; full setup
+is not repeated. The command saves only the explicitly confirmed private key
+configuration and Git-ignore protection; it does not install or change settings
+adapters. Newly granted sections work only where their consumers are already
+installed. Configure a hosted website's private key separately. A changed or
+custom adapter still requires review, not forced overwriting.
+
+For an operator's downloaded artifact, the installation is:
+
+```sh
+npm install --save-prod ./vendor/universalcms-connect-0.13.0.tgz
+```
+
+Use your project's package manager. These paths are examples for downloaded
+tarballs; Developer setup provides the actual hosted download URLs.
+
+The original-route mode uses the connector's bundled renderer and stylesheet.
+It does not create the optional SDK demo. Existing demo files remain preserved
+and keep their runtime dependency checks; repairing such an installation may
+still require the SDK, React renderer and Next adapter tarballs. The separate
+`init` and legacy `setup` flows retain that demo behavior.
+
+Before requesting a key or writing a delivery scaffold, `setup` checks installed
+runtime packages, compatible versions, production declarations and the React
+stylesheet. It checks again after confirmation; `server-key` performs the same
+checks for an existing scaffold. Missing or incomplete installations stop with a
+concrete install command using the saved CMS admin origin. A declaration alone
+does not prove a package is installed. These checks inspect bounded metadata and
+files without importing website code or running the package manager. A successful
+check still requires the website's build and rendered-delivery verification.
+
+The bundled connector itself must be declared in production `dependencies`, with
+the same installed version as the executing CLI and intact renderer/CSS exports.
+A cached or external CLI cannot substitute for that local runtime. Project-local
+pnpm links are supported; hoisted/shared workspace installations require review.
+
+CLI setup does not use an AI model, provider key or AI quota. For supported page
+layouts it prepares the same source import and published-content rendering
+boundaries used by an explicit developer integration. The CMS's Connect & fetch
+content action imports drafts; publishing remains an explicit CMS action.
+Full setup performs framework detection, complete source mapping and content-binding
+validation before its key prompt or integration writes. Explicit private key
+preparation is separate and does not verify an adapter. Unsupported layouts need a reviewed
+developer adapter; they never become a successful partial setup.
+
+Developer setup has three screens: **Set up website → Connect website → Setup
+summary**. Key creation and reuse are on the first screen. After installing the
+connector, run its scoped **Save server key privately** command. Paste the key
+only at the hidden terminal prompt and confirm the private save. Then run
+**Connect original website pages**, restart the website and check publication
+behavior before fetching. The server key stays on the website server; the browser
+checks original URLs and the public diagnostic without sending credentials.
+
+### Prepare the server key (0.9.1)
+
+The first screen supplies `server-key --prepare-only` with public connection
+flags. This explicitly prepares the private server environment before full setup
+or alongside a source-only integration. It stores the key in Git-ignored
+`.env.local` with owner-only access; credentials never enter command arguments,
+source exports or generated public files. Review the displayed API origin,
+website, environment and other public values before entering the key.
+
+Existing public and private connection bindings must agree. The command refuses
+invalid or changed configuration, unsafe files and conflicting environment
+overrides. It writes no renderer or public connection record and makes no network
+request. Saving a key does not verify its authorization, published delivery or
+website rendering. For a live deployment, configure the same private values in
+the hosting provider's server settings; local `.env.local` is not deployed by Git.
+The default `server-key` command, without `--prepare-only`, still requires an
+intact generated delivery integration.
+
+### Prepare content import (0.9.1)
+
+`setup-source --apply --require-server-key` remains an explicit migration-only
+command. It validates saved private bindings without installing publication or
+content rendering. `setup --original-routes-only` is the primary full-connection
+command and never silently falls back to source-only preparation. Source-only
+servers do not pass the CMS connection completion checks.
+
+The diagnostic reports the installed binding registry and a scoped publication
+read. `check-publication` additionally reads one original URL and checks its HTTP
+status and scoped runtime headers. Both distinguish unpublished pages (404) from
+failed delivery (503). These checks cannot prove DOM correctness: actual published
+text, draft isolation, native interactions and local/live deployment must be tested.
+
+`finalize-source --apply` closes the initial export only with intact full runtime
+and content bindings. Source handlers then return 410 without reading the saved
+baseline. Setup reruns preserve closure, and no original source or CMS publication
+is deleted. Run it only after importing and reviewing the source content. Review
+static assets and previous browser caches separately.
+
+The reviewed clothes-storefront profile binds 12 original pages to CMS documents
+while retaining its native layout and handlers. Tracking and stylist consultation
+remain website-owned. The reviewed ice-cream profile binds seven editorial pages
+and preserves 19 exact commerce URLs, including 16 product details. Their catalog,
+cart and checkout data remain website-owned. Both profiles check original module
+hashes and preserve imported block IDs. Changed or unrecognized compositions need
+review; these profiles are not general custom-router or commerce-data support.
+Setup never executes customer code or reads visitor inputs, browser storage or
+checkout state to discover content.
+
+Source-only Vite dev/preview now use the registered loopback port with strictPort.
+Stop the old server first; a busy or conflicting port fails rather than moving to
+another port. Run `check-source` after restarting, then fetch drafts in the CMS.
+Static hosting still needs a deployed server source adapter; local source setup
+does not deploy a live website.
+
+After saving source files, 0.7.3 checks the running endpoint and reports source
+readiness separately from file creation. An old Vite process keeps its original
+configuration until restarted; changing package scripts does not restart it.
+If the endpoint is missing or returns the SPA HTML, stop the old server, run the
+printed startup command in that project and repeat `check-source`. The check can
+read saved public source settings without requiring a private delivery key.
+Both setup methods validate the source, publication adapter, every registered
+original URL and installation of all twelve settings consumers before import.
+Intentionally ungranted settings remain disabled. A closed export skips the
+source fetch and remains eligible for publication rechecks. Rendered browser behavior and each
+live deployment remain separate evidence.
+
+`setup --original-routes-only` saves a public connection record alongside the
+complete reviewed integration, then offers key entry. A missing route mapping
+stops before any new connection/integration files or key prompt. `analyze` is an
+optional diagnostic: it only prints a report and cannot create `/api/cms-source`
+or prepare a website for Connect & fetch content. For unsupported layouts, finish
+the reviewed developer adapter before fetching content.
+
+The separate commands below remain available for existing scripts and staged use:
+
+1. **Connect the website.** Review and save its public connection settings.
+
+   ```sh
+   npx --no-install universalcms-connect connect \
+     --api-origin https://cms.example.com \
+     --site 11111111-1111-4111-8111-111111111111 \
+     --environment 22222222-2222-4222-8222-222222222222 \
+     --locale en \
+     --website-origin http://localhost:8080 \
+     --admin-origin http://localhost:3000
+   ```
+
+   Missing values are prompted in the terminal. After confirmation, `connect`
+   saves only `.universalcms/connection.json`: the API origin, site/environment
+   IDs, locale and website/admin origins. It does not authenticate, contact the
+   CMS, import content or save a key. It reads bounded existing private settings
+   to check their connection binding without displaying credentials. Keep the
+   public connection file with the integration.
+   Repeating the same connection is safe; a different connection or conflicting
+   saved runtime/source settings requires manual review and is refused.
+
+2. **Set up the integration.** Review the proposed files before saving.
+
+   ```sh
+   npx --no-install universalcms-connect setup
+   ```
+
+   Setup reads the saved connection, creates the source adapter, installs
+   publication checks and binds supported native page components to published
+   content at reviewed original URLs, including the homepage. It next requires a
+   separate review of all twelve settings consumers, including native header and
+   footer integration. An unsupported or declined stage leaves setup incomplete.
+   After that stage succeeds it asks **Save a server key now?** Accept to enter an
+   existing key through the hidden prompt and review its private save, or choose
+   No to create a key in the CMS first. Deferring leaves `.env.local` unchanged.
+   Canceling or failing the later key step retains the saved integration files.
+   Custom server/router code remains unchanged.
+
+3. **Save the server key if you deferred it.** Create an environment-scoped server delivery key in
+   Developer setup, then paste it into the hidden terminal prompt.
+
+   ```sh
+   npx --no-install universalcms-connect server-key
+   ```
+
+   The command checks that the generated delivery configuration matches the
+   saved connection. After confirmation, it saves private server settings to
+   `.env.local` with owner-only mode `0600` and excludes the file from Git. Never
+   add a key to a command, public configuration or an AI prompt. Full setup
+   supports server keys with Cache Components. The separate `setup-source` command
+   alone does not install publication checks or prepare private key entry.
+
+These commands do not install dependencies, execute website scripts, import CMS
+content or call AI. The connector bundles its shared content renderer; the
+additive `init` demo also needs the SDK and adapters described below. A saved connection and key do not establish successful API delivery or
+actual website rendering; verify those separately after publishing a page.
+
+Full `setup` installs publication checks before original public pages render.
+Review every proposed URL-to-kind/slug/locale mapping, including `/` to the home
+page. Published pages retain their existing components and design; missing or
+unpublished pages return HTTP 404. Delivery failures return HTTP 503 without
+original content. The completed settings integration resolves new published CMS
+page/post destinations and taxonomy archives; unknown or unpublished public URLs
+return 404. Private/account, API, admin, preview, framework and asset
+paths remain outside this public-page policy.
+
+The separate source-only command and additive `init` demo do not install this
+original-page protection. Upgrade older installations by rerunning full `setup`
+with 0.10.0, then restarting or rebuilding and deploying the website.
+Verify published, all-unpublished and publish-to-unpublish states using fixtures
+or disposable staging content at the original URLs, through direct requests,
+client navigation, reload and cached/prefetched routes. Do not change customer
+publications merely to test. Verify the documented rebuild/cache/deployment policy
+for static hosts. Successful API reads and demo routes do not establish that
+original pages follow CMS publication. Existing websites need the reviewed runtime
+integration and deployment; these instructions do not apply it automatically.
+Public migration exports and previously public assets remain separate concerns.
+
+For compatibility, running `setup` without `.universalcms/connection.json` keeps
+the combined guided flow: it asks for public values and a hidden server key,
+then writes the private settings and scaffold after one file-summary confirmation.
+It then requires the separate all-settings review; declining it leaves the saved
+core integration incomplete.
+Existing private values can be accepted with Enter; a saved key is never shown.
+That legacy flow can offer an optional published-page slug for a delivery check.
+Skipping or failing verification is reported as unverified delivery.
+
+For Next.js, setup uses the website and CMS admin origins to prepare
+`/api/cms-source`. Source export itself needs no delivery key; original-page
+publication checks do require one, including with Cache Components.
+Public static page discovery uses a bounded TypeScript parser without AI or
+executing your page code. In development every source request discovers new
+pages. Production uses a snapshot refreshed by `npm run build` before deployment;
+running `next build` directly bypasses npm's prebuild hook, so run `sync-source`
+first in that case. Deploy the new build before reconnecting from the CMS.
+
+For source-only setup:
+
+```sh
+npx --no-install universalcms-connect setup-source \
+  --website-origin http://localhost:8080 \
+  --admin-origin http://localhost:3000 \
+  --site 11111111-1111-4111-8111-111111111111 \
+  --environment 22222222-2222-4222-8222-222222222222
+# Review the plan, then repeat with --apply.
+npx --no-install universalcms-connect sync-source
+```
+
+Setup writes `.universalcms/source.config.json`, `source.generated.json`, a scoped
+Next route and a prebuild refresh hook. Commit the public configuration and
+snapshot with the integration. Keep the exact website/admin origins correct for
+each deployment. Existing custom source endpoints are preserved and need an
+explicit one-time integration of `createNextSourceHandler` with their reviewed
+`baseManifest`; listed `skipSlugs` retain those documents. Subsequent source
+refreshes preserve that adapter and reviewed content.
+
+Only public static pages are opted into automatic discovery. Review public-page
+scope at setup and use `excludedRoutes` in the public source config for paths or
+subtrees that must never be exported. Common private route names, middleware,
+auth-dependent pages/layouts and unknown conditionals are conservatively omitted.
+These guards cannot establish that an arbitrary application is public. The parser
+supports literal JSX text and selected immutable lists; forms, input values,
+private runtime state, imported components and database-backed/dynamic routes
+require an explicit public mapping. Unsupported content is reported, never
+replaced with placeholder pages. Layout/design and interaction are not copied.
+Inspect imported drafts before publishing. Existing CMS entries are preserved.
+
+`check-source --check-routes` compares static Next paths with the export (`/`
+maps to `home`). Missing pages fail the check, including deliberately excluded
+pages that need review; dynamic/custom/parallel routing stays unverified.
+React/Vite source setup can discover a directly mounted static App or flat literal
+React Router routes with local static page modules. It plans a nonempty manifest
+at `.universalcms/source.entries.json`, using the existing version 1 `{ version,
+entries }` contract, plus `.universalcms/content.routes.json` page bindings.
+It inspects the actual HTML/React entry without executing components. Custom
+history routers, guarded routes, dynamic data and incomplete extraction need a
+reviewed mapping; arbitrary router inference is not supported.
+Once mapped, `setup` or `setup-source --apply` creates a Vite source plugin wrapper
+and updates ordinary dev/preview scripts, preserving the original config. The
+normal package start command then serves `/api/cms-source` before HTML fallback.
+Missing/invalid mappings stop full setup before integration files or key prompts.
+Customized wrappers/start commands are preserved for manual integration.
+All entries must use the configured locale; apply private-route exclusions to the
+manifest itself. The public read sends no key and enforces exact scope, host and
+CMS origin. Local preview is supported, but static hosting needs a server endpoint.
+The package exports `universalCmsSource` and `createViteSourceHandler` from
+`@universalcms/connect/vite-source` for reviewed custom integrations.
+
+The original plan/apply commands remain available for advanced setup without
+writing a secret file:
+
+```sh
+npx --no-install universalcms-connect analyze
+npx --no-install universalcms-connect init \
+  --api-origin https://cms.example.com \
+  --site 11111111-1111-4111-8111-111111111111 \
+  --environment 22222222-2222-4222-8222-222222222222
+```
+
+After a public release, `npx @universalcms/connect@0.13.0 init` is the equivalent
+registry entry point. Copy the real IDs/API origin from **Developer setup**.
+Missing values are prompted in a terminal; `--non-interactive` fails instead.
+Init prints a plan. Run the same command with `--apply` after reviewing it.
+Use `--project <folder>`, `--locale <locale>` and a free Next `--mount /cms` as
+needed. `--dry-run` explicitly selects the default plan-only behavior.
+
+Then follow `.universalcms/SETUP.md`:
+
+1. Install the SDK and renderer (plus the Next adapter for Next). Before their
+   public release, install the supplied tarballs together. Setup never runs
+   package-manager installs or existing project scripts.
+2. Set `CMS_API_KEY` in your private server's secret environment using an
+   environment-scoped server delivery key from Developer setup. No provider key
+   or CMS administrator credentials are needed.
+3. Run `npx --no-install universalcms-connect check --slug YOUR_PUBLISHED_PAGE`.
+   The command uses the process key or a hidden terminal prompt. It honors the
+   same private `CMS_API_BASE_URL` override as the generated server, so run it
+   with that server's environment. It never saves the key.
+4. Run and build the website, verify rendering, then deploy its required server
+   and routing configuration. The generated guide provides exact commands.
+
+Next renders full supported blocks at `/cms/<published-page-slug>`. The original
+routes/design remain yours. Vite includes a standalone development demo, a React
+component, an additive dev-proxy wrapper and a private Node handler. For Vite
+production, deploy the static site **and** the private handler, and configure
+the host to proxy `/api/universalcms/page`; the Vite dev proxy is insufficient.
+
+For Vite websites with a detected existing Node server, full setup stops before
+saving files and requests an existing-server integration review. Keep the website's normal
+startup, SSR bootstrap and routes. Register `createPageHandler` from
+`@universalcms/connect/node` with its private fixed-scope SDK client before the
+existing API/SSR fallback; install the connector as a production dependency if
+using that entry point. The exported handler has no dependencies and never calls
+AI. The standalone raw-Vite demo is diagnostic only and must use an unused port;
+it does not replace the website's server. No existing server is edited by init.
+
+The first scaffold connects published **pages** in one locale. Existing design
+mapping, source import, posts/custom collections, taxonomies, navigation, forms,
+preview and SEO are deliberate follow-up integrations through the SDK. It does
+not silently create, import or publish CMS content. Successful API verification
+is distinct from a verified website deployment.
+
+### Diagnose Connect & fetch content
+
+The CMS button reads the website's **`/api/cms-source`** endpoint. Current Next.js
+`setup` prepares automatic public static-page discovery. Legacy `init` only
+prepares delivery scaffolding. React/Vite setup serves its reviewed public manifest through the normal dev command.
+Custom exporters need their explicit adapter; a delivery check alone is insufficient.
+
+Use the CMS's reviewed 0.13.0 package for the staged commands and current source
+discovery. Review source diagnostics and complete public
+mappings for unsupported pages. Restart the website using its normal server command, then run:
+
+```sh
+npx --no-install universalcms-connect check-source \
+  --website-origin http://localhost:8080 \
+  --admin-origin http://localhost:3000 \
+  --site 11111111-1111-4111-8111-111111111111 \
+  --environment 22222222-2222-4222-8222-222222222222
+```
+
+Replace the public values with the exact website/CMS origins and scope from
+Developer setup. `localhost` and `127.0.0.1` are different origins. No delivery
+key is needed, requested or sent. Supplying all four flags bypasses local saved
+configuration and works without running `init` or `setup`, including websites
+whose Next.js settings require manual integration. Otherwise missing values use
+sanitized `.env.local`/connector-config defaults. The command does not execute
+website code, change files, import content, make a CMS request or call AI.
+
+The read has a 10-second deadline, 20 MiB response budget, redirect rejection,
+fixed endpoint and exact scope/CORS checks. It validates the entire manifest's
+envelope, document shape, canonical identities and taxonomy assignments, up to
+1,000 entries. It prints fixed diagnostics and counts rather than returned
+content. A nonzero exit identifies a missing route, origin/scope mismatch, invalid
+manifest or other failed read; an empty export does not pass an existing-site check.
+
+A successful check is **not** complete authoring block-schema validation,
+inventory completeness or proof of browser access. Validate every complete
+document with the CMS v1 authoring schema, account for all public routes and
+unsupported mappings, and retry **Connect & fetch content** from the signed-in
+CMS browser. Browser local-network permissions may still need to be granted.
+The CLI must not loosen CORS or put a CMS key on the public source request.
+
+Analysis reads exact bounded project files and installed package metadata; it
+never evaluates configuration, runs website code, loads `.env`, crawls sites,
+uploads source or calls AI. Its sanitized JSON report can be supplied explicitly
+to Developer setup. AI provider configuration and metering belong to the platform;
+this connector works when AI is unavailable or its quota is exhausted.
+
+Init-generated files use exclusive creation; identical reruns are unchanged, conflicts
+stop before writes, symlinks and unsafe paths are rejected. Do not modify the
+project concurrently while setup applies: an interrupted or concurrently changed
+filesystem can leave a partial set of newly created files; rerun the same setup
+after inspection. Init does not replace or delete existing files. Staged setup
+keeps the connection fixed; changing the site, environment or origins requires
+manual review. The legacy guided flow without a connection record can replace
+unchanged generated files and private connection assignments after confirmation.
+Each file replacement is atomic; the overall multi-file operation can be
+interrupted after some settings or files have been saved.
+
+`check` performs a bounded published-page read with fixed site/environment/locale,
+no cookies and redirect rejection. It prints constant status messages, not returned
+content or credentials. Keys are never accepted as CLI flags, persisted in output,
+or put in `NEXT_PUBLIC_`/`VITE_` configuration. `server-key` and the legacy combined
+`setup` save secrets only to private `.env.local`, never generated documentation
+or public configuration. Unrelated private assignments and comments are preserved.
+Tracked secret files, unsafe links, ambiguous managed assignments, stale plans
+and conflicting process/development/production overrides are rejected. No
+install/postinstall hook runs.
+
+Development: `node scripts/build.mjs` makes the packed `dist` artifact and copies
+six reviewed analyzer/checker/provider sources from `integrations/custom`, plus
+the TypeScript parser and its Apache license from the locked workspace compiler. The tarball
+contains no workspace-relative imports. Its optional React peer is used only by website rendering, never by the CLI. Rebuild whenever
+those shared sources change. Run `tests/connect-package.test.ts` and the existing
+project-analysis, dependency-diagnostics and check-delivery tests before release.
+From the repository root, run `node integrations/connect/scripts/smoke.mjs`
+for production-build/browser verification using clean consumers and a synthetic
+CMS API. It defaults to offline dependency installation; `--online` permits
+public registry downloads and `--vite8` selects Vite 8.3 instead of Vite 7.3.
+It does not use customer records or live provider credentials.
+
+## Original-page publication control (0.6.1)
+
+Full `setup` installs publication checks for reviewed original URLs, including the
+exported homepage. Missing/unpublished entries return HTTP 404; failed delivery
+returns 503. Published pages retain their native design. Review the printed URL
+mapping before Save; use `.universalcms/publication.routes.json` for custom paths.
+Next 16 Cache Components is supported through a Node proxy. Standard Vite dev,
+preview and build use the publication plugin; run the generated `npm start` Node
+host for production. Static-only hosting cannot enforce this check.
+For loopback website origins, dev and preview use the saved port with strict port
+binding. Stop the dev server before starting preview; conflicting port overrides
+require correcting the connection or command rather than silently using another origin.
+
+Upgrade the connector, rerun setup and restart/deploy existing websites. Custom
+servers/proxies/layouts require review and do not silently receive a success
+claim. `init` remains an additive demo; `setup-source` exports content only.
+The browser rechecks open pages on focus/history/visibility and every 15 seconds.
+Full setup also installs the frozen source bindings described below; custom components use the same published-content provider.
+
+## Rendering published changes (0.6.1)
+
+Full `setup` binds supported public JSX/TSX page components to the delivered
+published document. Native elements and handlers remain mounted; stable imported
+block IDs select the content. Deleted blocks disappear, empty documents stay empty,
+and new blocks appear after the bound page body. Original native layout positions
+remain fixed; arbitrary section reordering and imported component internals need
+explicit mappings. Unsupported mappings stop setup before writes rather than
+reporting an availability-only integration as complete.
+
+Next App Router pages receive a request-time server wrapper and metadata from the
+same published revision. The reviewed configuration serves metadata in the initial
+HTML and disables a literal Cache Components flag only when the bounded source
+review finds no active `use cache`, `cacheLife` or `cacheTag` usage. Applications
+using those features need an explicit request-time integration; setup preserves
+their settings and stops before writes. Vite page modules receive a browser provider that waits
+for the private server's validated public projection before showing managed
+content. A directly mounted static App or flat literal React Router page tree can
+be discovered when there is no existing manifest. Other reviewed Vite routes
+require `.universalcms/content.routes.json`:
+
+```json
+[
+  { "path": "/", "sourceFile": "src/pages/Home.jsx" },
+  { "path": "/articles/story", "sourceFile": "src/pages/Story.jsx" }
+]
+```
+
+These modules must match their reviewed source manifest blocks. Existing AI import
+IDs are retained only when the entire ordered type/text/data structure matches.
+Custom routers and unmatched imports use an explicit reviewed binding through
+`@universalcms/connect/react-publication`; setup does not guess from similar text.
+The same runtime works for pages and posts, in development and on the generated
+production server. Static-only hosting needs a private runtime adapter or a
+separately verified rebuild/deployment pipeline.
+
+The `.universalcms/content.bindings.json` registry records source, native module,
+inventory and original-backup hashes. Reconnects and builds retain frozen import
+IDs. Concurrent edits, edited wrappers or changed native modules require review,
+so setup never silently regenerates CMS identities from edited text. Add routes
+through another reviewed setup. Keep original backups private to the project.
+
+For existing sites, install the new connector, rerun full setup, review the files,
+build and deploy to **each** local/live host. Updating the CMS or downloading a
+package does not modify already deployed website bundles. Existing AI integrations
+can use the shared provider/bindings while retaining their custom server/router.
+The AI setup prompt requires rendered revision-change tests on every deployed
+origin; API availability alone cannot pass that gate.
+
+
+Importing source creates editable drafts. Publication checks control availability;
+the website must also render the delivered document to display those edits. Saving
+a draft keeps the current public revision. **Update live / Publish** creates the
+new public revision.
+
+Server components can read the current document with the same reviewed route
+registry and private `CMS_API_KEY` used by the publication proxy:
+
+```js
+import { createPublishedDocumentReader, publicPublishedEntry } from '@universalcms/connect/publication';
+import configuration from './.universalcms/publication.config.json' with { type: 'json' };
+
+const readPublished = createPublishedDocumentReader({ configuration });
+const result = await readPublished('/about');
+// Handle missing as 404 and unavailable as 503; never fall back to old page text.
+if (result.state === 'published') {
+  const entry = publicPublishedEntry(result.entry);
+  // Pass entry.document to the website's reviewed native components or renderer.
+}
+```
+
+The Next proxy and Vite host also serve `GET /api/universalcms/document?path=/about`.
+Only registered public paths are accepted; scope and the server key stay on the
+server. The published response contains `state`, `revision` and `entry`. Custom
+fields, unknown properties and form notification destinations are omitted from
+this browser projection. Private server readers can explicitly map approved
+custom fields themselves. Missing publications return 404 and failed delivery
+returns 503. Responses use no-store caching.
+The existing publication-status response remains `{ "state": "published" }` for
+older browser scripts. The current script requests a revision token with
+`X-UniversalCMS-Include-Revision: 1`; this avoids breaking open tabs during an upgrade.
+
+Preserve the imported block IDs in an explicit component mapping. Do not regenerate
+them from edited text or blindly replace matching DOM text. Shared phrases,
+collections and imported components need distinct reviewed slots. Handle removed
+blocks without restoring stale literals and define where added blocks render.
+
+To keep an open page current, emit a meta element named
+`universalcms-publication-revision`, with `content` equal to the rendered revision
+token and `data-path` equal to its registered path. The browser checks publication
+on focus and every 15 seconds. A changed revision reloads the page by default;
+a provider can handle the cancelable `universalcms:publication-change` event,
+fetch the public document, update its React state, and then update the meta token.
+The provider must handle failed/missing responses without retaining old content.
+Full setup now creates these native component bindings for supported source modules. The source-only importer remains separate.
+
+Production publication tests use synthetic content and a private fixture key:
+`node scripts/test-connect-next-publication.mjs` (from the repository root), then
+`node integrations/connect/scripts/publication-smoke.mjs` with
+`UNIVERSALCMS_SMOKE_VITE_MODULE` set to an installed Vite 6/7/8
+`dist/node/index.js` file. Build the connector first; both scripts require local
+HTTP listeners and installed Chrome. They do not change customer publications.