feat: stabilize Velite 1.0 public API and Zod 4 pipeline

.agents/AGENTS.md

@@ -0,0 +1,54 @@
+# `.agents/` — AI Workspace
+
+This directory is the central hub for AI-related artefacts for this repository. It is **not** part of the shipped codebase.
+
+## Two directories, two purposes
+
+| Directory    | Purpose                                                    | Lifetime           | Tracked in git?     |
+| ------------ | ---------------------------------------------------------- | ------------------ | ------------------- |
+| `knowledge/` | Stable conventions every session (human + AI) must follow  | Long-lived, edited | **Yes**             |
+| `sessions/`  | Transient session artefacts: plans, scratch notes, reports | Per-session        | **No** (gitignored) |
+
+If a finding is universal and reusable → it belongs in `knowledge/`.
+If it is "what we did this session" or "where we are right now" → it belongs in `sessions/`.
+
+## Layout
+
+```
+.agents/
+├── AGENTS.md                          ← this file
+├── knowledge/                         ← stable, long-lived AI conventions (tracked)
+│   └── ...
+└── sessions/                          ← transient per-session scratch (gitignored)
+    ├── .gitignore                     ← ignores session subfolders, tracks AGENTS.md
+    ├── AGENTS.md                      ← session folder rules & naming
+    └── YYYYMMDD-HHmm-{slug}/         ← one folder per session
+        ├── plan.md
+        ├── notes.md
+        ├── report.md
+        └── ...
+```
+
+## Git policy
+
+- `knowledge/` is **tracked** — commit conventions here like any other source file.
+- `sessions/.gitignore` ignores all session subfolders (`*/`). To commit a session on a feature branch for review context, add an un-ignore line (e.g. `!20260617-1430-schema-refactor`). Remove it before merging to `main`.
+- Session folders must **never** be merged into `main`. Promote durable findings to `knowledge/` before cleanup.
+
+## When to create a session
+
+**Create a new session** when the user starts a new, unrelated task or a previous session is finished.
+
+**Reuse the existing session** when the user says "continue", "keep going", or the work spans multiple conversations on the same task.
+
+When unsure, list recent sessions (`ls -1t sessions/`) and ask.
+
+## Knowledge directory
+
+`knowledge/` holds conventions discovered during development that future sessions should follow. Examples:
+
+- Naming conventions specific to this repo
+- Non-obvious build or test patterns
+- Decisions with rationale that aren't obvious from the code
+
+Each file should be short, factual, and named by topic (e.g. `schema-patterns.md`, `testing-notes.md`).

.agents/sessions/.gitignore

@@ -0,0 +1,6 @@
+# AI Agents sessions — only AGENTS.md is committed; session subfolders are ignored
+*/
+
+# You can temporarily include the current session directory in your branch for a better DX
+# Remove this before merging, or it will cause noise in master
+# e.g. `!20260427-1200-schema-refactor`

.agents/sessions/AGENTS.md

@@ -0,0 +1,114 @@
+# `.agents/sessions/` — AI Session Workspace
+
+Transient scratch space for AI-assisted sessions: plans, research notes, status reports, and any artefact that helps a human or a future AI session pick up where the previous one left off.
+
+**Not** part of the codebase. **Not** for source code.
+
+---
+
+## Git policy
+
+`sessions/.gitignore` ignores all session subfolders by default — only `sessions/AGENTS.md` is tracked. Session subfolders are ignored so casual `git add .` never sweeps them up.
+
+### Opting a session into a feature branch (recommended)
+
+Session artefacts are valuable review context. To commit a session folder on a feature branch, add an un-ignore line to `sessions/.gitignore`:
+
+```
+!20260617-1430-schema-refactor
+```
+
+### Hard rule: do NOT merge session content into main
+
+Before merging:
+
+1. Remove the `!<session-folder>` un-ignore line from `sessions/.gitignore`.
+2. `git rm -r --cached .agents/sessions/<session-folder>/` to drop from index.
+3. Commit the cleanup, then merge.
+
+If a session artefact has long-term value, **promote it** to `../knowledge/` (or another appropriate location) before the cleanup commit.
+
+---
+
+## Layout
+
+```
+.agents/sessions/
+├── .gitignore                     ← this file: ignores session subfolders
+├── AGENTS.md                      ← session folder rules & naming (this file)
+└── YYYYMMDD-HHmm-{slug}/         ← one folder per session (gitignored)
+    ├── plan.md
+    ├── notes.md
+    ├── report.md
+    └── ...
+```
+
+---
+
+## Session folder naming
+
+Format: `YYYYMMDD-HHmm-{slug}`
+
+- `YYYYMMDD-HHmm` — local time when the session started.
+- `{slug}` — short, lowercase, kebab-case description of the task. 2-5 words.
+- Examples:
+  - `20260617-1430-schema-refactor`
+  - `20260617-1500-fix-asset-dedup`
+  - `20260618-0900-doc-cleanup`
+
+If two sessions collide on the same minute, append `-2`, `-3`, etc. to the slug.
+
+---
+
+## When to create a new session vs. reuse an existing one
+
+**Create a new session** when:
+
+- The user starts a new, unrelated task.
+- A previous session is finished (`report.md` written) and a follow-up has a different goal.
+
+**Reuse the existing session** when:
+
+- The user says "continue", "keep going", "next step", or references the previous task.
+- The work is the same task spread across multiple conversations.
+- An open `todo.md` or `plan.md` still has unfinished items relevant to the new turn.
+
+When unsure, list the most recent session folders (`ls -1t .agents/sessions/`) and ask the user which to resume, or default to the most recent if it clearly matches.
+
+---
+
+## Files inside a session
+
+All optional. Only create what the task actually needs.
+
+| File         | Purpose                                                         |
+| ------------ | --------------------------------------------------------------- |
+| `plan.md`    | Goal, constraints, ordered steps, decisions still to make       |
+| `notes.md`   | Findings, snippets, code references (`file:line`), observations |
+| `report.md`  | Final summary when the task ends — what shipped, what didn't    |
+| `todo.md`    | Outstanding actionable items, with owner if known               |
+| `context.md` | Background a future session must know to make sense of the work |
+| `logs.md`    | Verbatim command output / tool runs only when materially useful |
+
+---
+
+## Writing rules
+
+1. Markdown only. No binaries, no screenshots unless the user provides them.
+2. Bullet points and tables over prose. Aim for skimmable.
+3. Reference source code with `path/to/file.ts:lineNumber`, never paste large source blocks.
+4. Record decisions **and the reasoning** — future you will not remember why.
+5. English only, matching the rest of the repo.
+6. No secrets, tokens, passwords, or anything unsafe in a public gist.
+7. Treat every session folder as ephemeral. If something must survive, promote it.
+
+---
+
+## Quality bar
+
+A reviewer opening a session folder cold should, within ~2 minutes, answer:
+
+- What was the goal?
+- What is the current state?
+- What changed in the actual codebase?
+- What, if anything, is still pending?

.github/workflows/docs.yml

@@ -20,18 +20,31 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
+      - name: Checkout
+        uses: actions/checkout@v5
         with:
           fetch-depth: 0
-      - uses: pnpm/action-setup@v4
-      - uses: actions/setup-node@v6
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v6
         with:
-          node-version: 22
+          node-version: 24
           cache: pnpm
-      - uses: actions/configure-pages@v5
-      - run: pnpm install
-      - run: pnpm docs:build && touch docs/.vitepress/dist/.nojekyll
-      - uses: actions/upload-pages-artifact@v4
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v4
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build with VitePress
+        run: pnpm docs:build
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
         with:
           path: docs/.vitepress/dist
 
@@ -41,5 +54,8 @@ jobs:
       url: ${{ steps.deployment.outputs.page_url }}
     needs: build
     runs-on: ubuntu-latest
+    name: Deploy
     steps:
-      - uses: actions/deploy-pages@v4
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/main.yml

@@ -10,12 +10,23 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
-      - uses: pnpm/action-setup@v4
-      - uses: actions/setup-node@v6
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v6
         with:
-          node-version: lts/*
+          node-version: 22.13.0
           cache: pnpm
-      - run: pnpm install
-      - run: pnpm build
-      - run: pnpm test
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build
+        run: pnpm build
+
+      - name: Test
+        run: pnpm test

.github/workflows/publish.yml

@@ -1,28 +1,76 @@
 name: Publish
 
 on:
-  push:
-    tags:
-      - v*
+  release:
+    types: [published]
+  workflow_dispatch:
 
 permissions:
-  id-token: write  # Required for OIDC
   contents: read
+  id-token: write
 
 jobs:
   publish:
-    # prevents this action from running on forks
-    if: github.repository == 'zce/velite'
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
-      - uses: pnpm/action-setup@v4
-      - uses: actions/setup-node@v6
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v6
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
         with:
-          node-version: lts/*
-          registry-url: https://registry.npmjs.org/
-          package-manager-cache: false  # never use caching in release builds
-      - run: pnpm install
-      - run: pnpm build
-      - run: pnpm test
-      - run: pnpm publish --no-git-checks
+          node-version: 22.13.0
+          registry-url: https://registry.npmjs.org
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build
+        run: pnpm build
+
+      - name: Test
+        run: pnpm test
+
+      - name: Build docs
+        run: pnpm docs:build
+
+      - name: Resolve npm tag
+        run: |
+          if [ "${{ github.event.release.prerelease }}" = "true" ]; then
+            echo "NPM_TAG=next" >> "$GITHUB_ENV"
+          elif node -e "process.exit(require('./package.json').version.includes('-') ? 0 : 1)"; then
+            echo "NPM_TAG=next" >> "$GITHUB_ENV"
+          else
+            echo "NPM_TAG=latest" >> "$GITHUB_ENV"
+          fi
+
+      - name: Publish core package
+        run: |
+          VERSION=$(node -p "require('./package.json').version")
+          if npm view "velite@$VERSION" version >/dev/null 2>&1; then
+            echo "velite@$VERSION is already published; skipping."
+          else
+            pnpm --filter velite publish --access public --provenance --no-git-checks --tag "$NPM_TAG"
+          fi
+
+      - name: Publish Next.js plugin
+        run: |
+          VERSION=$(node -p "require('./packages/next/package.json').version")
+          if npm view "@velite/plugin-next@$VERSION" version >/dev/null 2>&1; then
+            echo "@velite/plugin-next@$VERSION is already published; skipping."
+          else
+            pnpm --filter @velite/plugin-next publish --access public --provenance --no-git-checks --tag "$NPM_TAG"
+          fi
+
+      - name: Publish Vite plugin
+        run: |
+          VERSION=$(node -p "require('./packages/vite/package.json').version")
+          if npm view "@velite/plugin-vite@$VERSION" version >/dev/null 2>&1; then
+            echo "@velite/plugin-vite@$VERSION is already published; skipping."
+          else
+            pnpm --filter @velite/plugin-vite publish --access public --provenance --no-git-checks --tag "$NPM_TAG"
+          fi

.vscode/settings.json

@@ -8,5 +8,6 @@
   "files.exclude": {
     "**/node_modules": true
   },
-  "typescript.tsdk": "node_modules/typescript/lib"
+  "js/ts.referencesCodeLens.enabled": true,
+  "js/ts.tsdk.path": "node_modules/typescript/lib"
 }