vite-plugin-zephyr 1.5.0 → 1.6.0

package/README.md

@@ -36,32 +36,32 @@ pnpm add --dev vite-plugin-zephyr
 bun add --dev vite-plugin-zephyr
 ```
 
-## Usage
+## AI Agent Skills (Optional)
+
+This package ships the `zephyr-vite` Agent Skill for AI coding agents, together
+with the shared `zephyr-core` and `zephyr-module-federation` guides. The
+skills are versioned with the package, so your agent reads guidance that
+matches the release you installed.
 
-### Agent guidance
+Zephyr does not need Intent at runtime. Coding agents only find these skills
+after you opt in with
+[TanStack Intent](https://tanstack.com/intent/latest/docs/getting-started/quick-start-consumers):
 
-This package ships the `zephyr-vite` Agent Skill alongside its implementation.
-Use the installed package's guidance for configuration and build lifecycle
-behavior rather than a repository skill from a different SDK release.
+```sh
+pnpm add -D @tanstack/intent
+pnpm dlx @tanstack/intent@latest install
+```
 
-Install Intent as a development dependency when adding agent tooling is appropriate:
+Allow `vite-plugin-zephyr` when `install` asks. Intent saves that choice in the
+`intent.skills` allowlist in your `package.json`. To check or load the skill
+yourself:
 
 ```sh
-pnpm add -D @tanstack/intent@0.5.0
-pnpm exec intent install
 pnpm exec intent list
 pnpm exec intent load 'vite-plugin-zephyr#zephyr-vite'
 ```
 
-Select `vite-plugin-zephyr` during setup. The consumer's `intent.skills` allowlist
-controls which installed packages appear in the agent's catalog. Intent is agent
-tooling; the Zephyr plugin does not require it at runtime.
-
-Every published Zephyr package also bundles `zephyr-core` and
-`zephyr-module-federation` from the canonical guides in this repository.
-Plugin setup and cross-bundler configuration no longer live in the separate
-skills repository. Maintainers run `pnpm skills:check` at the
-workspace root after updating the guidance and recording source reviews.
+## Usage
 
 ### Basic Configuration
 

package/dist/lib/vite-plugin-zephyr.js

@@ -554,8 +554,18 @@ function withZephyrCore(options = {}) {
                 return null;
             }
         },
-        buildStart () {
+        async buildStart () {
             environmentBuildStarted = true;
+            try {
+                const engine = await zephyr_engine_defer;
+                if (engine.sourceContext && engine.sourceCapture?.phase !== 'build-start' && !engine.pendingSourceCapture) {
+                    const capture = (0, external_zephyr_agent_namespaceObject.captureSource)(engine.sourceContext, 'build-start');
+                    if (engine.hasActiveBuild) engine.sourceCapture = capture;
+                    else engine.pendingSourceCapture = capture;
+                }
+            } catch (error) {
+                (0, external_zephyr_agent_namespaceObject.handleGlobalError)(error);
+            }
         },
         buildEnd (error) {
             if (error) directBuildFailed = true;

package/dist/lib/vite-plugin-zephyr.mjs

@@ -2,7 +2,7 @@ import { readFile } from "node:fs/promises";
 import { createHash, randomUUID } from "node:crypto";
 import { createRequire } from "node:module";
 import magic_string from "magic-string";
-import { ApplicationContext, ZeErrors, ZephyrEngine, ZephyrError, assertZephyrBuildTarget, claimPartialAssetMapBatch, commitPartialAssetMapClaimBatch, createManifestContent, handleGlobalError, logFn, normalizeBasePath, rewriteEnvReadsToVirtualModule, rollbackPartialAssetMapClaimBatch, savePartialAssetMap, zeBuildAssets, zeBuildDashData, ze_log } from "zephyr-agent";
+import { ApplicationContext, ZeErrors, ZephyrEngine, ZephyrError, assertZephyrBuildTarget, captureSource, claimPartialAssetMapBatch, commitPartialAssetMapClaimBatch, createManifestContent, handleGlobalError, logFn, normalizeBasePath, rewriteEnvReadsToVirtualModule, rollbackPartialAssetMapClaimBatch, savePartialAssetMap, zeBuildAssets, zeBuildDashData, ze_log } from "zephyr-agent";
 import { extractEntrypoint } from "./internal/extract/extract-entrypoint.mjs";
 import { extract_mf_plugins } from "./internal/extract/extract_mf_plugin.mjs";
 import { extract_vite_assets_map } from "./internal/extract/extract_vite_assets_map.mjs";
@@ -514,8 +514,18 @@ function withZephyrCore(options = {}) {
                 return null;
             }
         },
-        buildStart () {
+        async buildStart () {
             environmentBuildStarted = true;
+            try {
+                const engine = await zephyr_engine_defer;
+                if (engine.sourceContext && engine.sourceCapture?.phase !== 'build-start' && !engine.pendingSourceCapture) {
+                    const capture = captureSource(engine.sourceContext, 'build-start');
+                    if (engine.hasActiveBuild) engine.sourceCapture = capture;
+                    else engine.pendingSourceCapture = capture;
+                }
+            } catch (error) {
+                handleGlobalError(error);
+            }
         },
         buildEnd (error) {
             if (error) directBuildFailed = true;

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://raw.githubusercontent.com/vitejs/vite-plugin-registry/refs/heads/main/data/schema/extended-package-json.schema.json",
   "name": "vite-plugin-zephyr",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "Vite plugin for Zephyr",
   "keywords": [
     "deploy",
@@ -55,13 +55,13 @@
     "acorn": "^8.18.0",
     "acorn-walk": "^8.3.5",
     "magic-string": "1.2.3",
-    "zephyr-agent": "1.5.0"
+    "zephyr-agent": "1.6.0"
   },
   "devDependencies": {
     "@module-federation/vite": "1.21.2",
     "@rslib/core": "1.0.0",
     "@rstest/core": "0.11.12",
-    "@tanstack/intent": "0.5.0",
+    "@tanstack/intent": "0.5.3",
     "@types/node": "^24.13.3",
     "rollup": "^4.63.1",
     "typescript": "~7.0.0",

package/skills/zephyr-core/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: zephyr-core
-description: Use when the user asks about Zephyr setup, with-zephyr, SDK selection, versions, tags, environments, snapshot/version URLs, dashboard workflows, docs, or public env vars.
+description: Use when the user asks about Zephyr setup, with-zephyr, SDK selection, Change Attribution, human/AI contributions, dirty-source version differences, versions, tags, environments, snapshot/version URLs, dashboard workflows, docs, or public env vars.
 license: Apache-2.0
 metadata:
   author: Zephyr Cloud IO
@@ -10,6 +10,40 @@ metadata:
 sources:
   - ZephyrCloudIO/zephyr-packages:**/skills/zephyr-core/references/*.md
   - ZephyrCloudIO/zephyr-packages:**/scripts/sync-package-skills.mjs
+  - ZephyrCloudIO/zephyr-packages:**/libs/with-zephyr/src/attribution.ts
+  - ZephyrCloudIO/zephyr-packages:**/libs/with-zephyr/hooks/*.cjs
+  - ZephyrCloudIO/zephyr-packages:**/libs/with-zephyr/src/index.ts
+  - ZephyrCloudIO/zephyr-packages:**/libs/with-zephyr/src/rstack.ts
+  - ZephyrCloudIO/zephyr-packages:**/libs/with-zephyr/src/bundlers/rstack.ts
+  - ZephyrCloudIO/zephyr-packages:**/libs/with-zephyr/src/bundlers/index.ts
+  - ZephyrCloudIO/zephyr-packages:**/libs/with-zephyr/src/engine/ast-grep.ts
+  - ZephyrCloudIO/zephyr-packages:**/libs/with-zephyr/src/operations.ts
+  - ZephyrCloudIO/zephyr-packages:**/libs/with-zephyr/src/types.ts
+  - ZephyrCloudIO/zephyr-packages:**/libs/with-zephyr/src/tests/bundler-configs.test.ts
+  - ZephyrCloudIO/zephyr-packages:**/libs/with-zephyr/src/tests/rstack.test.ts
+  - ZephyrCloudIO/zephyr-packages:**/libs/with-zephyr/src/tests/rstack-inheritance.test.ts
+  - ZephyrCloudIO/zephyr-packages:**/libs/with-zephyr/src/tests/codemod.test.ts
+  - ZephyrCloudIO/zephyr-packages:**/libs/with-zephyr/src/tests/attribution.test.ts
+  - ZephyrCloudIO/zephyr-packages:**/libs/with-zephyr/README.md
+  - ZephyrCloudIO/zephyr-packages:**/libs/zephyr-agent/src/lib/change-attribution/*.ts
+  - ZephyrCloudIO/zephyr-packages:**/libs/zephyr-agent/src/lib/transformers/ze-build-snapshot.ts
+  - ZephyrCloudIO/zephyr-packages:**/libs/zephyr-agent/src/lib/transformers/ze-build-dash-data.ts
+  - ZephyrCloudIO/zephyr-packages:**/libs/zephyr-agent/src/zephyr-engine/index.ts
+  - ZephyrCloudIO/zephyr-packages:**/libs/zephyr-edge-contract/src/lib/change-attribution.ts
+  - ZephyrCloudIO/zephyr-packages:**/libs/zephyr-edge-contract/src/index.ts
+  - ZephyrCloudIO/zephyr-packages:**/libs/zephyr-edge-contract/src/lib/snapshot.ts
+  - ZephyrCloudIO/zephyr-packages:**/libs/zephyr-edge-contract/src/lib/zephyr-build-stats.ts
+  - ZephyrCloudIO/zephyr-packages:**/scripts/verify-change-attribution.mjs
+  - ZephyrCloudIO/zephyr-packages:**/scripts/verify-live-attribution.mjs
+  - ZephyrCloudIO/zephyr-packages:**/scripts/verify-attribution-storage.mjs
+  - ZephyrCloudIO/zephyr-packages:**/libs/zephyr-agent/src/index.ts
+  - ZephyrCloudIO/zephyr-packages:**/libs/zephyr-agent/src/lib/http/http-request.ts
+  - ZephyrCloudIO/zephyr-packages:**/libs/zephyr-agent/src/lib/http/http-request.test.ts
+  - ZephyrCloudIO/zephyr-packages:**/libs/zephyr-agent/src/lib/http/fetch-with-retries.ts
+  - ZephyrCloudIO/zephyr-packages:**/libs/zephyr-agent/src/lib/http/fetch-with-retries.test.ts
+  - ZephyrCloudIO/zephyr-packages:**/libs/zephyr-agent/src/lib/node-persist/upload-provider-options.ts
+  - ZephyrCloudIO/zephyr-packages:**/libs/zephyr-agent/src/zephyr-engine/__test__/upload_assets.test.ts
+  - ZephyrCloudIO/zephyr-packages:**/libs/zephyr-edge-contract/src/lib/api-contract-negotiation/get-api-contract.ts
 ---
 
 # Zephyr Core
@@ -58,6 +92,9 @@ Zephyr is a build-integrated deployment platform for frontend and frontend-adjac
 5. Read `references/examples-resume.md` when the user wants concrete starter patterns.
 6. Read `references/docs-map.md` when deeper docs links are useful.
 7. Read `references/troubleshooting.md` when setup/build/auth/git issues appear.
+8. Read `references/change-attribution.md` for optional tracking, agent/editor hooks,
+   source fingerprints, and version comparisons involving local changes. Obtain
+   explicit opt-in before enabling capture or installing hooks.
 
 ## Source priorities
 

package/skills/zephyr-core/references/attribution-storage.md

@@ -0,0 +1,144 @@
+# Attribution storage and repository policy
+
+Read this when selecting storage, controlling source-text sharing, or implementing
+the endpoint. First enable tracking with [Change Attribution](change-attribution.md).
+
+## Repository preferences
+
+Commit `.zephyr/attribution.json` at the Git root. Each repo has its own file;
+apps in a monorepo share its capture preferences. It contains preferences, never
+credentials, custom endpoint URLs, or a claimed account tier:
+
+```json
+{ "schemaVersion": 1, "enabled": true, "storage": "local" }
+```
+
+Storage configuration requires an existing enabled repository; enable with
+`with-zephyr . --attribution` first. A blank codemod storage answer preserves
+existing preferences. Missing `storage`, including older configs, means **local**. Source copies,
+attribution, and version receipts stay in the worktree Git directory. Local
+mode neither resolves attribution credentials nor makes attribution requests,
+and attaches no attribution to uploaded snapshots/build stats. Ordinary Zephyr
+deployment still uploads its assets and normal deployment metadata.
+
+```bash
+pnpm exec ze-cli attribution configure --storage remote
+# Paid/BYOC: independently choose source-text fields.
+pnpm exec ze-cli attribution configure --storage remote --patches include --lines omit
+pnpm exec ze-cli attribution status
+```
+
+| Mode/account       | Source text sent                                        |
+| ------------------ | ------------------------------------------------------- |
+| Local, any account | None                                                    |
+| Remote, free       | Unified patch and structured changed-line text required |
+| Remote, paid       | Neither by default; either/both optional                |
+| Remote, BYOC       | Neither by default; either/both optional                |
+
+Free remote source-text opt-out is rejected before sending. Choose local to keep
+it local. Tier comes from authenticated service policy, not repo configuration
+or deployment provider. Paid/BYOC shared preferences can include
+`"content": { "patch": false, "lines": false }` or enable either field.
+
+All remote records include file hashes, attribution ranges/origins, and available
+session/model/effort/usage metadata. `patch` is the unified difference against the
+**captured Git HEAD**, with ordinary context. `lines` contains text/origin of
+added/removed lines. A patch inherently contains line text even when `lines` is
+false; omit both to share no source text. Range positions/origins remain metadata.
+New files can have every line in their difference. Full source snapshots and
+binary contents are not uploaded. Exclusions apply to working source and HEAD.
+Remote payloads are limited to 20 MiB. Server version comparisons need the Git
+baseline; patches cannot reconstruct unchanged committed files on their own.
+
+## Private restriction and precedence
+
+Keep this checkout local even when its shared config selects remote:
+
+```bash
+pnpm exec ze-cli attribution configure --storage local --local
+```
+
+This atomically writes `zephyr-attribution/config.local.json` inside the worktree
+Git directory with owner-only POSIX file permissions. It preserves shared config
+and cannot enable remote or additional content. Deliberately remove that file
+to resume shared settings. Local receipts also use owner-only files: this is
+filesystem protection, not disk encryption. Windows relies on worktree ACLs.
+
+Private restrictions apply first. Sharing requires both repo opt-in and server
+authorization. An optional shared `repositoryId` must match the service's
+application/repository binding. Unknown fields, including tokens, URLs, and tier,
+are rejected by configuration commands. Invalid or newer configuration at build
+time disables sharing without blocking deployment; the SDK does not ignore
+unrecognized permissions and accidentally authorize remote uploads. Credentials use existing SDK authentication/private storage; CI
+supplies credentials through its secret environment.
+
+## Control-plane contract and secure persistence
+
+The SDK implements the client and shared types. **Server endpoints, policy
+management, encryption, retention, and BYOC routing are not implemented in this
+workspace.** Remote publication requires `ATTRIBUTION_POLICY` in authenticated
+application configuration, with this shape:
+
+```json
+{
+  "schemaVersion": 1,
+  "repositoryId": "repo-123",
+  "revision": "policy-revision-7",
+  "storage": "remote",
+  "tier": "paid",
+  "content": { "patch": true, "lines": true }
+}
+```
+
+Policy `content` is the server's allowlist, not source-text opt-in. Paid/BYOC
+repo preferences still default off; free requires both allowed and included.
+Persist policy by organization/repository, allow repo-admin updates, retain
+revision/audit history, and derive tier from billing/BYOC entitlement. A repo
+file must never be able to claim a different tier.
+
+The client sends `AttributionUploadRequest` to **`POST /attribution`** on the
+existing authenticated API gateway. It includes application/repository/build/
+snapshot IDs, policy revision, effective content flags, attribution metadata,
+and optional HEAD comparison. It resolves bearer credentials at request time,
+requires HTTPS (loopback HTTP for fixtures), refuses redirects, and omits response
+bodies from diagnostics. Raw prompts, agent responses, transcript paths, and
+full source copies are excluded.
+
+The server must authenticate the caller, authorize repository access, verify
+application/build ownership, independently enforce current tier/content policy
+and revision, and reject stale or unauthorized requests. Deduplicate the
+repository/application/build `Idempotency-Key`: return the original record for
+retries and reject conflicting evidence for the same build. Store immutable
+records tied to those IDs and source fingerprint.
+
+Return `AttributionUploadResponse`: `status: "ok"`, opaque record ID, matching
+application/repository/build/snapshot IDs, and source fingerprint. Only after
+acknowledgment does the client put a small record reference in snapshots and
+build stats. Full evidence stays at the private endpoint. A private delivery
+receipt stays locally. If policy, source capture, credentials, delivery, or
+acknowledgment is unavailable, deployment continues without an attribution
+reference and emits a warning; source evidence stays local when capture succeeded.
+This also permits deployment before the control-plane endpoint ships. Reconcile pending records when the build publishes and expire
+orphaned records from failed deployments.
+
+Store policy in an access-controlled database and source evidence in private
+encrypted object storage using managed keys. Keep storage credentials in a
+service secret manager. Authorize evidence reads by repo membership, enforce
+retention/deletion, and audit policy changes/access without logging source
+bodies. Resolve BYOC destinations/credentials through authorized server
+configuration, never a repo-supplied URL. These are server requirements, not
+guarantees established by the client test.
+
+## Verification
+
+Build the agent and CLI, then run against a disposable generated app:
+
+```bash
+node scripts/verify-attribution-storage.mjs /tmp/zephyr-attribution-demo
+```
+
+The built CLI/SDK and real loopback HTTP fixture verify tier defaults, independent
+content flags, local isolation, build IDs, stable retry identity, rejected
+acknowledgments/redirects, and private restrictions. The verifier restores shared
+config and writes a private `storage-test-report.json`. Production authorization,
+encryption, retention, and BYOC routing require separate server verification.

package/skills/zephyr-core/references/change-attribution.md

@@ -0,0 +1,172 @@
+# Change Attribution
+
+Use when enabling optional human/AI attribution or comparing versions built from
+uncommitted source. The Zephyr Attribution integration uses Git AI; a skill alone
+cannot reliably observe file writes.
+
+## Enable with consent
+
+The `with-zephyr` CLI offers **Enable Change Attribution** after SDK setup in an
+interactive terminal. It links to [Git AI installation](https://usegitai.com/docs/get-started)
+and separately offers **Install Agent Integrations**. Non-interactive invocation
+does not opt in; `--dry-run` and `--no-attribution` do not create configuration.
+Explicit non-interactive setup:
+
+```bash
+pnpm dlx with-zephyr . --attribution --attribution-agents codex claude grok
+```
+
+Storage defaults to **local**. The interactive offer also asks local versus
+remote; `--attribution-storage remote` selects remote explicitly. Read
+[repository storage and policy](attribution-storage.md) before enabling remote:
+free accounts include patches/changed-line text; paid/BYOC defaults omit them.
+
+This writes repository-root `.zephyr/attribution.json` and merges hooks into
+`.codex/hooks.json`, `.claude/settings.json`, and/or `.grok/hooks/zephyr-attribution.json`. Codex/Grok also install `.zephyr/attribution-hook.cjs` for metadata. It preserves existing hooks
+and settings, validates documents before writing, and does not modify global
+settings or grant hook trust. Review the Codex project hooks with `/hooks` and
+restart agent sessions. Grok requires its native project trust review (`/hooks-trust`); this grants folder trust for its other project integrations too. T3 uses the same Grok integration through ACP. Install the Git AI binary separately through its linked
+instructions; the codemod does not run a downloaded installer. Skip the agents
+flag for source capture only, or when existing Git AI hooks already cover the
+agents. The installer may also configure agent hooks globally; avoid duplicating
+the same integration at global and project scope.
+
+Known human evidence needs a Git AI editor integration, available through the
+same setup link. Agent hooks alone do not establish which remaining edits were
+human. Missing evidence always remains **unknown**.
+
+## Source records and comparisons
+
+An opted-in SDK captures repository-wide Git-eligible working-tree files,
+including unstaged and untracked files, rather than substituting HEAD or the
+index. A deterministic fingerprint covers paths, file modes, and content hashes.
+Private immutable source copies and version-to-source receipts stay under the
+worktree's Git directory, in `zephyr-attribution/`. They are never build assets.
+Comparisons require those local copies; a fresh clone cannot retrieve them from
+Zephyr or Git AI notes. They are not synchronized or pruned automatically.
+
+Install `zephyr-cli` to inspect the records without login or deployment:
+
+```bash
+pnpm exec ze-cli attribution status
+pnpm exec ze-cli attribution capture --format json
+# Use the two sourceId values returned by capture, or local Zephyr snapshot IDs.
+pnpm exec ze-cli attribution compare <before> <after> --format json
+```
+
+Use `-C <project>` to select another project. Differences report additions,
+removals, binary changes, and file modes. Attribution on a removed line describes
+its original contributor; it does not identify who deleted it. Reverted edits
+disappear from the net source difference.
+
+Local mode attaches no attribution to uploaded snapshots or build stats. Remote
+mode sends full evidence to a dedicated private endpoint and includes a small
+acknowledged record reference in snapshot/build-stat `changeAttribution`. The
+authenticated snapshot `creator` remains the deployer; contributor identities
+are self-reported Git AI evidence, not verified people. Server endpoint/policy
+persistence and a dashboard version-difference UI require control-plane support
+and are not implemented in this SDK workspace.
+
+## Harness, prompt initiator, effort, and usage
+
+`workspaceHuman` identifies the Git author associated with a capture. Hooks-off AI
+changes can appear under this identity, but their edit origin remains unknown.
+The Git author, prompting human, and authenticated snapshot creator are separate.
+Set `ZE_ATTRIBUTION_INITIATOR` in each person's launcher environment to record the
+prompt initiator, and `ZE_ATTRIBUTION_HARNESS` to identify a wrapper such as `t3`
+versus `codex-cli`. For T3, configure these in the selected project/provider's
+environment settings. These are self-reports, not verified account assertions;
+do not put a shared person's identity into team-wide hooks. Missing values stay
+absent. A skill cannot reliably prove which person typed a prompt.
+
+Codex/Grok collect a private metadata ledger under the worktree Git directory.
+Line origins join exact tool-call identities into `sessions`, keyed by agent,
+native session, and turn. Model and effort changes retain the earlier turn's
+metadata. Codex effort/provider/counters use a bounded optional rollout adapter
+tested with CLI 0.160.0; rollout parsing is not a stable API. Grok model/effort
+use its observed summary and usage files, tested with CLI 1.0.46 and T3 0.0.44.
+Unsupported/missing metadata does not invent defaults. Grok uses Git AI's public
+`agent-v1` interface; no fork is required for this bridge.
+
+Grok 1.0.46 omits prompt IDs on tool events. The bridge brackets an active prompt
+from `UserPromptSubmit` to `Stop`/cancellation and marks `turnAssociation` as
+`active-prompt`, an inferred association. Native Codex turn IDs are marked
+`native-turn-id`. Unassociated/background completions stay unknown. Concurrent
+or background Grok work needs stronger native event linkage before claiming an
+exact prompt association. Integration labels alone do not prove the harness.
+
+Usage and cost belong to sessions, not individual lines. Session-cumulative
+snapshots are **not additive**, including across model switches or versions.
+The captured cost is either unavailable or harness-reported USD ticks with an
+observation timestamp and partial flag. It is not inferred from token counts or
+presented as an invoice. [xAI defines one USD as 10 billion USD ticks](https://docs.x.ai/developers/cost-tracking).
+Hook-time Grok counters can lag a turn; only a native
+finished-turn match refreshes them, otherwise they remain incomplete/partial.
+Historical source receipts retain their observed metadata. Raw prompts,
+responses, transcript paths, and arbitrary provider fields are not published.
+
+## Coverage and correctness
+
+- Git-ignored files, common build output (`dist`, `build`, `.next`, `.nuxt`,
+  `.output`), dependency/cache folders, `.env*`, `.npmrc`, `.netrc`, and private
+  key extensions are excluded. Add repository-relative prefixes to `exclude`
+  in the configuration. This is a scoped source record, not a complete build
+  reproduction or a general secret detector.
+- Captures are limited to 20,000 files and 50 MiB. Submodules need exclusions.
+  Failures produce `unavailable` metadata rather than a partial source claim.
+- Vite and `ze-cli <build>` observe source at build start and snapshot creation.
+  `boundary-match` means those two observations match; it does not prove no
+  transient edit occurred between observations. `changed-during-build` means
+  the records differ and neither should be presented as the exact consumed
+  inputs. Other engine adapters observe their generation start and publication;
+  prebuilt deployments observe upload preparation rather than the earlier compiler
+  invocation. Each generation uses at most one start and one publication copy.
+- The Git AI working-log adapter supports `checkpoint/1.0.0` from Git AI 1.7.x,
+  tested with 1.7.5. It accepts attribution only when the checkpoint's content
+  hash matches the captured file. Stale checkpoints remain unknown. Committed
+  blame is deferred to files changed in local/remote comparisons, only for bytes
+  matching the captured commit. Captures retain working-checkpoint ranges and
+  mark matching committed bytes privately; unchanged files do not trigger blame
+  processes at build start. HEAD trees are read once and missing baseline blobs
+  in one batch. Comparison enrichment never rewrites the original receipts. Legacy untracked
+  `Human` checkpoints are not known-human evidence.
+  Since Git AI 1.7 JSON blame omits known humans, the adapter follows native Git
+  line origins into explicit `authorship/3.0.0` human attestations in local
+  `refs/notes/ai`. A commit's ordinary author is never sufficient evidence.
+- `gitAiPath` can point to a compatible fork. Keep format changes behind the
+  adapter; don't infer authorship from file style or the absence of AI marks.
+
+To disable capture, set `enabled` to `false`. Remove the installed Git AI and metadata command
+entries from project hook documents to stop those hooks, retaining other hooks.
+Existing local receipts remain available until explicitly deleted.
+
+## Maintainer verification
+
+`scripts/verify-change-attribution.mjs` builds an actual generated React/Vite app
+three times with the local SDK. It uses the real Git AI binary and replays Codex
+and editor hook fixtures, including a model field. It replaces the cloud transport
+and checks same-commit source differences containing AI, known-human, and unknown
+origins. Hook replays verify integration compatibility; they do not establish
+that a real human typed the fixture or that a live Codex session used that model.
+
+After building `create-zephyr-apps`, `with-zephyr`, `zephyr-agent`, `zephyr-cli`,
+and `vite-plugin-zephyr` locally:
+
+```bash
+node libs/create-zephyr-apps/dist/index.js /tmp/zephyr-attribution-demo --template react-vite --package-manager pnpm --git --install --json
+node libs/with-zephyr/dist/index.js /tmp/zephyr-attribution-demo --attribution --attribution-agents codex --git-ai-path /absolute/path/to/git-ai
+node scripts/verify-change-attribution.mjs /tmp/zephyr-attribution-demo /absolute/path/to/git-ai
+```
+
+Use a disposable app: the verifier edits its template source and writes a private
+`demo-report.json`. It needs Git AI's background service running. A replay failure
+or missing evidence must fail verification, not be relabeled as human or AI.
+
+For live trials, retain a source receipt after each real agent edit. The
+`scripts/verify-live-attribution.mjs <generated-app> <manifest.json>` verifier
+loads those private records, checks the expected model/effort/harness and actual
+added line, compares versions sharing a commit, then builds the final app using
+real Vite/SDK snapshot construction with cloud transport disabled. Manifest
+cases specify `name`, `sourceId`, `file`, `text`, `kind`, and optional `model`,
+`effort`, `harness`. These receipts are local observations, not cloud deployments.
+Do not substitute hook replay for a requested live model/harness trial.

package/skills/zephyr-core/references/sdk-setup.md

@@ -36,6 +36,11 @@ Why: the codemod detects the stack and makes the smallest setup change for suppo
 
 ## SDK picker
 
+For optional human/AI provenance, the codemod also offers **Change Attribution**
+and links to Git AI installation. Enabling capture and installing project agent
+hooks are separate choices. Read [Change Attribution](change-attribution.md) for
+consent, supported integrations, dirty-source records, and coverage limits.
+
 Use the official picker doc first:
 
 - Docs page: `https://docs.zephyr-cloud.io/getting-started/find-your-sdk`
@@ -50,6 +55,8 @@ Current mapping:
 | Webpack           | `zephyr-webpack-plugin`             |
 | Rspack            | `zephyr-rspack-plugin`              |
 | Rsbuild / Rslib   | `zephyr-rsbuild-plugin`             |
+| Rstack app / lib  | `zephyr-rsbuild-plugin`             |
+| Rstack doc        | `zephyr-rspress-plugin`             |
 | Rollup            | `rollup-plugin-zephyr`              |
 | Rolldown          | `zephyr-rolldown-plugin`            |
 | Parcel            | `parcel-reporter-zephyr`            |
@@ -144,6 +151,35 @@ Source example: `https://github.com/ZephyrCloudIO/zephyr-examples/blob/main/fram
 
 ## Important setup notes
 
+For Rstack CLI, run `pnpm dlx with-zephyr --bundlers rstack --dry-run` before
+applying the same command without `--dry-run`. The codemod discovers
+`rstack.config.ts`, `.js`, `.mts`, and `.mjs`, then configures `define.app()`,
+`define.lib()`, and `define.doc()` independently. It preserves other tool
+sections and existing plugins, reuses imported Zephyr aliases, and adds each
+dependency to the nearest project manifest. Inline objects and configuration
+functions returning inline objects are supported; imported configurations and
+spreads without explicit `plugins`, or placed after `plugins`, require manual setup. Custom config filenames
+are not discovered. Use the existing Rsbuild or Rspress plugin, not a separate
+Rstack package. If local builds must not deploy, explicitly gate the plugin in
+the deployment workflow rather than assuming the codemod makes builds read-only.
+
+Rstack automatically inherits app/library plugins into Rstest, including inline
+projects. Generated and existing direct Zephyr registrations therefore gain an
+`RSTEST` environment guard, using a collision-free import from `node:process`.
+This excludes only Zephyr during tests, preserving inherited aliases, transforms,
+and other plugins. Build commands still include Zephyr; optional deployment
+opt-in must retain the test guard. Integration detection considers plugin-list
+expressions, not calls inside nested callbacks, methods, or metadata. Factory
+rewrites leave nested object/class method returns untouched and only reuse
+imports when no enclosing lexical declaration shadows them.
+
+Existing global `process.env.RSTEST` and `process.env['RSTEST']` guards remain
+unchanged, including imports. A local or imported `process` binding is not trusted
+as the global guard and still receives the collision-free environment guard.
+
+Malformed Rstack files are isolated to that file; other selected configurations
+still run. The bundler filter excludes other tools before parsing their files.
+
 - Plugin placement is stack-specific, not globally “always last”.
 - Nx compose-plugin setups usually put Zephyr last in the composition.
 - Vite Module Federation and framework-specific integrations can require a specific order; verify against the stack docs/example before moving plugins around.

package/skills/zephyr-vite/SKILL.md

@@ -6,7 +6,7 @@ description: Configure and deploy Vite applications with vite-plugin-zephyr; use
   integrations for TanStack Start and Vinext.
 metadata:
   library: vite-plugin-zephyr
-  library_version: '1.5.0' # x-release-please-version
+  library_version: '1.6.0' # x-release-please-version
   purpose: Configure an existing Vite application for Zephyr publication while preserving its framework plugins and selecting the correct build lifecycle.
   domain: vite
   type: core
@@ -108,3 +108,15 @@ asset correctness, but not live deployment success. Report that distinction.
 On failure, retain the actionable error and fix the matching configuration or
 publication issue. Do not silently change the framework integration, suppress
 errors, or claim that a partial build was deployed.
+
+## Optional Change Attribution
+
+The bundled `zephyr-core/references/change-attribution.md` covers explicit
+opt-in and project agent hooks. With capture enabled, Vite observes source at
+`buildStart` and snapshot creation, including dirty and eligible untracked files.
+Matching boundaries do not prove exact compiler inputs; changed boundaries must
+be reported as such. Local storage sends no attribution. Remote storage requires
+authenticated repository policy and the dedicated endpoint, then publishes only
+its acknowledged record reference. Read `attribution-storage.md` alongside the
+shared guide for content controls. Client verification does not establish server
+persistence or dashboard support. Missing/stale Git AI evidence remains unknown.