chore(deps): bump softprops/action-gh-release from 2 to 3

.github/readme/README.en.md

@@ -142,6 +142,21 @@ After filling in the variables, wait about 3 minutes for the deployment to finis
 
 ## Advanced Configuration
 
+### Connect AI Agents for Analysis
+
+InsightFlare exposes Skills for AI Agents. You can connect your InsightFlare deployment to agents such as OpenClaw, Codex, Claude Code, and others, so they can access InsightFlare data directly for analysis and report generation.  
+Send the following instruction to your Agent, replacing the domain with your deployed InsightFlare instance. Your Agent will guide you to the dashboard to create a dedicated API key for accessing InsightFlare data.
+
+```txt
+Read https://<your InsightFlare domain>/.well-known/skills.json, connect to this web analytics system, and guide me through authorization.
+```
+
+Then you can ask your Agent questions in natural language, for example:
+
+```txt
+"How did my site perform last month? Where did most visitors come from among the highest-traffic sites? Which pages were the most popular?"
+```
+
 ### Override Wrangler Configuration with Cloudflare Variables
 
 In Cloudflare build environments, you can use project variables and secrets to override deployment-specific values from `wrangler.toml`. `build:pre` reads these values before deployment, writes them into the active Wrangler config, and the following `wrangler deploy` uses the resolved config.
@@ -295,7 +310,7 @@ Set `NEXT_PUBLIC_DEMO_MODE=1` to make the development server automatically enabl
 | Command                           | Purpose                                     |
 | --------------------------------- | ------------------------------------------- |
 | `npm run dev`                     | Local dashboard development                 |
-| `npm run check`                   | Run typecheck + lint + format + i18n checks |
+| `npm run check`                   | Run typecheck + lint + format + i18n + tests + spec checks |
 | `npm run typecheck`               | TypeScript type checking                    |
 | `npm run lint` / `lint:fix`       | ESLint                                      |
 | `npm run format` / `format:check` | Prettier                                    |

.github/readme/README.zh.md

@@ -142,6 +142,21 @@ Cloudflare 会自动 Clone 这个仓库、创建并绑定所需要的资源。
 
 ## 进阶配置
 
+### 接入 AI Agents 进行分析
+
+我们开放了用于 AI Agents 的 Skills，您可以选择将 InsightFlare 接入您的 Agents，例如 OpenClaw、Codex、Claude Code 等, 让 Agents 能够直接访问 InsightFlare 的数据，进行分析和报告生成。  
+请直接发送下面的指令给您的 Agent，您需要域名换成您部署的 InsightFlare 实例。您的 Agents 会指引您前往仪表盘为其创建一个专用 API 密钥，便于其访问 InsightFlare 的数据。
+
+```txt
+阅读 https://<您的 InsightFlare 域名>/.well-known/skills.json，接入这个访问分析系统，并指引我进行授权。
+```
+
+随后，您可以以任意自然语言向 Agent 提问，例如：
+
+```txt
+“上个月，我的站点的访问情况如何？访问量最高的站点中，访客大都是来自哪里的？哪些页面最受欢迎？”
+```
+
 ### 使用 Cloudflare 变量覆盖 Wrangler 配置
 
 在 Cloudflare 的构建环境中，可以通过「变量和密钥」覆盖 `wrangler.toml` 中需要因部署而变化的配置。`build:pre` 会在部署前读取这些变量并写入当前 Wrangler 配置，随后 `wrangler deploy` 会使用覆盖后的配置。
@@ -295,7 +310,7 @@ InsightFlare 的前端 SDK 支持以手动调用的方式上报自定义事件
 | 命令                              | 用途                                           |
 | --------------------------------- | ---------------------------------------------- |
 | `npm run dev`                     | 本地开发仪表板                                 |
-| `npm run check`                   | 一键执行 typecheck + lint + format + i18n 校验 |
+| `npm run check`                   | 一键执行 typecheck + lint + format + i18n + test + spec 校验 |
 | `npm run typecheck`               | TypeScript 类型检查                            |
 | `npm run lint` / `lint:fix`       | ESLint                                         |
 | `npm run format` / `format:check` | Prettier                                       |

.github/workflows/release.yml

@@ -47,7 +47,18 @@ jobs:
           echo "file_path=$NEW_FILE" >> "$GITHUB_OUTPUT"
           echo "Detected release changelog: $NEW_FILE"
 
-      - name: Sync package versions
+      - name: Setup Node.js
+        if: steps.changelog.outputs.has_release == 'true'
+        uses: actions/setup-node@v6
+        with:
+          node-version: 24
+          cache: npm
+
+      - name: Install dependencies
+        if: steps.changelog.outputs.has_release == 'true'
+        run: npm ci
+
+      - name: Sync release artifacts
         if: steps.changelog.outputs.has_release == 'true'
         shell: bash
         run: |
@@ -83,16 +94,20 @@ jobs:
           updatePackageLock("package-lock.json");
           NODE
 
-          git add package.json package-lock.json
+          npm run generate:openapi
+          npm run generate:skills
+          npx tsx scripts/check-openapi-contract.ts
+
+          git add package.json package-lock.json docs/openapi.json docs/openapi.yaml docs/skills.json
 
           if git diff --cached --quiet; then
-            echo "Package versions are already up to date."
+            echo "Release artifacts are already up to date."
             exit 0
           fi
 
           git config user.name "github-actions[bot]"
           git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
-          git commit -m "chore(release): sync package version to ${{ steps.changelog.outputs.version }} [skip ci]"
+          git commit -m "chore(release): sync release artifacts to ${{ steps.changelog.outputs.version }} [skip ci]"
           git push origin HEAD:${{ github.ref_name }}
 
       - name: Finalize release commit
@@ -114,7 +129,7 @@ jobs:
 
       - name: Create release
         if: steps.changelog.outputs.has_release == 'true'
-        uses: softprops/action-gh-release@v2
+        uses: softprops/action-gh-release@v3
         with:
           tag_name: ${{ steps.changelog.outputs.version }}
           name: Release ${{ steps.changelog.outputs.version }}

.gitignore

@@ -14,4 +14,4 @@ src/tracker/sdk.min.ts
 src/tracker/sdk.no-perf.min.ts
 coverage
 logs/
-
+plan/

changelog/v0.2.0.md

@@ -0,0 +1,35 @@
+InsightFlare v0.2.0 expands the product from a dashboard-first analytics app into a more integration-ready analytics service with a documented API surface, API key authentication, and stronger request validation.
+
+This release focuses on making InsightFlare easier to connect with external tools and safer to expose programmatically. It introduces API key management, a versioned API contract, OpenAPI and agent discovery endpoints, and a more consistent API response model.
+
+## Highlights
+
+- Added API key management, including scoped keys, API key authentication, and dashboard controls for creating and managing access.
+- Introduced the versioned `/api/v1` API surface with generated OpenAPI 3.1 documentation and request/response examples.
+- Added `.well-known` discovery endpoints for OpenAPI, agent skills, health, security, and account password-change metadata.
+- Added generated `skills.json` documentation so LLM and agent clients can understand the public API more easily.
+- Added stronger request validation through shared Zod schemas for analytics, realtime, site, team, funnel, tracker, and common API inputs.
+- Improved API response consistency with request IDs, timestamps, and a unified response envelope.
+- Added same-origin request validation and strengthened secret/session handling for safer deployments.
+- Added dashboard surfaces for API key management and clearer version update details.
+- Improved geography and realtime dashboard rendering by moving heavier map and realtime views into dedicated client-side stages.
+
+## Changes Since v0.1.0
+
+- Fixed API version reporting so it is read from `package.json` instead of being hardcoded.
+- Fixed `/api/v1` root route matching with an optional catch-all route.
+- Aligned generated OpenAPI metadata, schemas, examples, and endpoint behavior with the actual implementation.
+- Fixed mobile page scrolling behavior.
+- Fixed rollback secret handling so fallback values are applied correctly.
+- Replaced hardcoded locale checks with the i18n system.
+- Renamed the funnel route to `funnels` for consistency.
+- Removed unnecessary release-summary height restrictions.
+- Reduced worker bundle pressure by moving heavier dashboard experiences behind client-only islands.
+
+## Developer Experience
+
+- Added scripts for generating OpenAPI and skills documentation.
+- Added an OpenAPI contract checker to catch documentation drift.
+- Added CI coverage thresholds and broadened test coverage across API v1, API keys, scheduled tasks, hourly rollups, realtime mocks, schemas, validation, and dashboard client data.
+- Added explicit Prettier defaults and stricter ESLint coverage for the codebase.
+- Added environment and prebuild checks for safer Cloudflare deployment flows.