Add changelog feature

.github/CODEOWNERS

@@ -0,0 +1,4 @@
+# Changelog entries are reviewed by the changelog-reviewers team.
+# The changelog-action bot opens PRs; humans approve.
+/changelog/      @gokite-ai/changelog-reviewers
+/changelog/**    @gokite-ai/changelog-reviewers

.github/workflows/changelog-build.yml

@@ -0,0 +1,38 @@
+name: Rebuild changelog index
+
+on:
+  pull_request:
+    paths:
+      - "changelog/**"
+  push:
+    branches: [main]
+    paths:
+      - "changelog/**"
+
+jobs:
+  rebuild:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.head_ref || github.ref }}
+          token: ${{ secrets.CHANGELOG_BOT_TOKEN }}
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: npm
+      - run: npm ci
+      - run: npm run build:changelog
+      - name: Commit regenerated files if changed
+        run: |
+          if [ -n "$(git status --porcelain changelog/README.md SUMMARY.md public/changelog/index.json)" ]; then
+            git config user.name 'changelog-bot'
+            git config user.email 'changelog-bot@users.noreply.github.com'
+            git add changelog/README.md SUMMARY.md public/changelog/index.json
+            git commit -S -m "chore(changelog): regenerate index"
+            git push
+          else
+            echo "Nothing to regenerate."
+          fi

.github/workflows/changelog-commands.yml

@@ -0,0 +1,121 @@
+name: Changelog reviewer commands
+on:
+  issue_comment:
+    types: [created]
+
+jobs:
+  dispatch:
+    if: |
+      github.event.issue.pull_request != null &&
+      startsWith(github.event.issue.title, 'Changelog:') &&
+      (startsWith(github.event.comment.body, '/regenerate') ||
+       startsWith(github.event.comment.body, '/skip'))
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write
+      contents: write
+    steps:
+      - name: Acknowledge
+        uses: actions/github-script@v7
+        with:
+          script: |
+            await github.rest.reactions.createForIssueComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              comment_id: context.payload.comment.id,
+              content: 'eyes'
+            });
+
+      - name: Parse PR metadata
+        id: meta
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const pr = await github.rest.pulls.get({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              pull_number: context.payload.issue.number,
+            });
+            const branch = pr.data.head.ref;
+            // The PR body carries a machine-parseable line written by
+            // the changelog action:
+            //   <!-- changelog-action: component=<c> tag=<t> -->
+            // We read component and tag from there rather than reverse-
+            // engineering from the branch name, because date-style tags
+            // (e.g. 2026-05-20) cannot round-trip from the dash-encoded
+            // branch.
+            const body = pr.data.body || '';
+            const m = body.match(/<!--\s*changelog-action:\s*component=([a-z]+)\s+tag=(\S+)\s*-->/);
+            if (!m) throw new Error('PR body is missing the changelog-action metadata comment');
+            const component = m[1];
+            const tag = m[2];
+            // Explicit component -> repo mapping. Names don't all follow
+            // passport-<component>.
+            const REPO_MAP = {
+              backend: 'passport',
+              web: 'passport-web',
+              cli: 'passport-cli',
+              skills: 'passport-skills',
+            };
+            const componentRepo = REPO_MAP[component];
+            if (!componentRepo) throw new Error(`Unknown component: ${component}`);
+            core.setOutput('branch', branch);
+            core.setOutput('component', component);
+            core.setOutput('tag', tag);
+            core.setOutput('component_repo', componentRepo);
+
+      - name: Checkout component repo for /regenerate
+        if: startsWith(github.event.comment.body, '/regenerate')
+        uses: actions/checkout@v4
+        with:
+          repository: gokite-ai/${{ steps.meta.outputs.component_repo }}
+          token: ${{ secrets.CHANGELOG_BOT_TOKEN }}
+          fetch-depth: 0
+          fetch-tags: true
+
+      - name: Run changelog action for /regenerate
+        if: startsWith(github.event.comment.body, '/regenerate')
+        uses: gokite-ai/gha-actions/changelog@main
+        with:
+          component: ${{ steps.meta.outputs.component }}
+          tag: ${{ steps.meta.outputs.tag }}
+          # Pass all three keys; the action selects in priority order
+          # (anthropic > openai > deepseek) based on which are set.
+          # Configure the keys you have as org-level secrets; unset
+          # ones simply resolve to empty strings and are skipped.
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+          openai_api_key: ${{ secrets.OPENAI_API_KEY }}
+          deepseek_api_key: ${{ secrets.DEEPSEEK_API_KEY }}
+          github_token: ${{ secrets.CHANGELOG_BOT_TOKEN }}
+
+      - name: Replace file with placeholder for /skip
+        if: startsWith(github.event.comment.body, '/skip')
+        uses: actions/github-script@v7
+        env:
+          BRANCH: ${{ steps.meta.outputs.branch }}
+        with:
+          script: |
+            const { BRANCH } = process.env;
+            const files = await github.rest.pulls.listFiles({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              pull_number: context.payload.issue.number,
+            });
+            const target = files.data.find(f => f.filename.startsWith('changelog/') && f.filename.endsWith('.md'));
+            if (!target) throw new Error('No changelog file in this PR');
+            const existing = await github.rest.repos.getContent({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              path: target.filename,
+              ref: BRANCH,
+            });
+            const fm = `---\ndate: ${new Date().toISOString().slice(0,10)}\ncomponent: placeholder\nversion: skipped\ntag: skipped\nrepo: gokite-ai/unknown\nrelease_url: https://github.com\ntitle: "Internal maintenance release"\nsummary: "No user-facing changes."\nai_generated: true\ngenerated_at: ${new Date().toISOString()}\ncorrected_at: null\n---\n\n## What changed\n\nInternal maintenance release with no user-facing changes.\n\n<details>\n<summary>Included changes</summary>\n\n<!-- BEGIN auto-generated; do not hand-edit -->\n_Skipped via /skip command._\n<!-- END auto-generated -->\n\n</details>\n`;
+            await github.rest.repos.createOrUpdateFileContents({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              path: target.filename,
+              message: 'Skip via reviewer command',
+              content: Buffer.from(fm, 'utf8').toString('base64'),
+              branch: BRANCH,
+              sha: existing.data.sha,
+            });

SUMMARY.md

@@ -55,3 +55,15 @@
 * [LayerZero-Kite AI](kite-chain/10-layerzero-kite-integration/README.md)
 * [Goldsky-Kite AI](kite-chain/11-goldsky-kite-integration/README.md)
 * [Lucid-Kite AI](kite-chain/12-lucid-kite-integration/README.md)
+
+
+## 📜 Changelog
+
+* [All changes](changelog/README.md)
+<!-- changelog-entries-start -->
+* [Backend v1.1.0 — Session preflight now returns merchant fee estimates](changelog/2026/2026-05-19-backend-v1-1-0.md)
+* [CLI v1.3.4 — Activity command now filters by date range and merchant](changelog/2026/2026-05-19-cli-v1-3-4.md)
+* [Skills v0.9.1 — request-session skill now retries preflight on transient catalog errors](changelog/2026/2026-05-19-skills-v0-9-1.md)
+* [Web v1.2.0 — Session approval page shows estimated fees alongside budget cap](changelog/2026/2026-05-19-web-v1-2-0.md)
+<!-- changelog-entries-end -->
+

changelog/2026/2026-05-19-backend-v1-1-0.md

@@ -0,0 +1,29 @@
+---
+date: 2026-05-19
+component: backend
+version: v1.1.0
+tag: v1.1.0
+repo: gokite-ai/passport
+release_url: https://github.com/gokite-ai/passport/releases/tag/v1.1.0
+title: "Session preflight now returns merchant fee estimates"
+summary: "The preflight endpoint includes an estimated_fees field so agents can show users a realistic total spend cap before they approve a session."
+ai_generated: false
+generated_at: 2026-05-19T18:00:00Z
+corrected_at: null
+---
+
+## What changed
+
+When an agent constructs a session delegation, the preflight call now returns an `estimated_fees` object covering the catalog's known merchant fees, network gas, and Passport's own service margin. Approval pages can show users an itemized "up to ~$X" total instead of just a raw budget cap.
+
+This estimate is informational only — actual fees still come from the merchant at transaction time — but it makes high-budget sessions less surprising and reduces post-approval support questions.
+
+<details>
+<summary>Included changes</summary>
+
+<!-- BEGIN auto-generated; do not hand-edit -->
+- feat(session): return estimated_fees in preflight response
+- feat(catalog): track per-service fee metadata
+<!-- END auto-generated -->
+
+</details>

changelog/2026/2026-05-19-cli-v1-3-4.md

@@ -0,0 +1,29 @@
+---
+date: 2026-05-19
+component: cli
+version: v1.3.4
+tag: v1.3.4
+repo: gokite-ai/passport-cli
+release_url: https://github.com/gokite-ai/passport-cli/releases/tag/v1.3.4
+title: "Activity command now filters by date range and merchant"
+summary: "kpass activity supports --since, --until, and --merchant flags so agents can answer 'what did I spend on X last week?' without fetching the full history."
+ai_generated: false
+generated_at: 2026-05-19T18:00:00Z
+corrected_at: null
+---
+
+## What changed
+
+The `kpass activity` command previously returned the full event history with no way to narrow the result set. Agents asking "what did I spend on Amazon last week?" had to fetch everything and filter locally, which was slow on accounts with many sessions.
+
+You can now pass `--since YYYY-MM-DD`, `--until YYYY-MM-DD`, and `--merchant <name>` to filter on the server side. Results are paginated, and the JSON envelope adds a `truncated: true` flag when the result set hits the page limit.
+
+<details>
+<summary>Included changes</summary>
+
+<!-- BEGIN auto-generated; do not hand-edit -->
+- feat(activity): add --since/--until/--merchant flags
+- fix(activity): respect --output json with truncation indicator
+<!-- END auto-generated -->
+
+</details>

changelog/2026/2026-05-19-skills-v0-9-1.md

@@ -0,0 +1,29 @@
+---
+date: 2026-05-19
+component: skills
+version: v0.9.1
+tag: v0.9.1
+repo: gokite-ai/passport-skills
+release_url: https://github.com/gokite-ai/passport-skills/releases/tag/v0.9.1
+title: "request-session skill now retries preflight on transient catalog errors"
+summary: "Sessions targeting catalog services no longer fail immediately when the catalog returns a 503 — the skill retries with backoff before surfacing the error."
+ai_generated: false
+generated_at: 2026-05-19T18:00:00Z
+corrected_at: null
+---
+
+## What changed
+
+`request-session` previously treated any non-200 response from the catalog preflight as a hard failure, which meant transient catalog blips would abort otherwise-valid session approvals. The skill now retries 503 and timeout responses up to three times with exponential backoff before propagating the error.
+
+Approval cancellations attributable to catalog flakiness should drop noticeably. Permanent errors (404 service-not-found, 403 unauthorized) are still surfaced immediately so agents don't waste time retrying.
+
+<details>
+<summary>Included changes</summary>
+
+<!-- BEGIN auto-generated; do not hand-edit -->
+- feat(request-session): retry preflight on 503/timeout
+- docs(request-session): document the retry behavior in SKILL.md
+<!-- END auto-generated -->
+
+</details>

changelog/2026/2026-05-19-web-v1-2-0.md

@@ -0,0 +1,29 @@
+---
+date: 2026-05-19
+component: web
+version: v1.2.0
+tag: v1.2.0
+repo: gokite-ai/passport-web
+release_url: https://github.com/gokite-ai/passport-web/releases/tag/v1.2.0
+title: "Session approval page shows estimated fees alongside budget cap"
+summary: "Users approving a new session see an itemized 'up to ~$X' estimate next to the raw budget cap, matching the new backend preflight data."
+ai_generated: false
+generated_at: 2026-05-19T18:00:00Z
+corrected_at: null
+---
+
+## What changed
+
+The session approval page now renders the new `estimated_fees` field from the backend preflight. Users see the budget cap and an itemized "up to ~$X" estimate covering merchant fees, network gas, and Passport's service margin.
+
+The estimate is labeled as informational; the underlying budget cap still controls actual spending. We added a small "what counts as a fee?" tooltip to explain the breakdown.
+
+<details>
+<summary>Included changes</summary>
+
+<!-- BEGIN auto-generated; do not hand-edit -->
+- feat(approval): render estimated_fees breakdown
+- feat(approval): add fee-breakdown tooltip
+<!-- END auto-generated -->
+
+</details>

changelog/README.md

@@ -0,0 +1,43 @@
+# Changelog
+
+Public delivery timeline for Kite Passport — see each component's recent releases below.
+
+<!-- changelog-index-start -->
+## May 19, 2026
+
+### Backend · v1.1.0
+**Session preflight now returns merchant fee estimates**
+
+The preflight endpoint includes an estimated_fees field so agents can show users a realistic total spend cap before they approve a session.
+
+[Read full notes →](2026/2026-05-19-backend-v1-1-0.md)
+
+### CLI · v1.3.4
+**Activity command now filters by date range and merchant**
+
+kpass activity supports --since, --until, and --merchant flags so agents can answer 'what did I spend on X last week?' without fetching the full history.
+
+[Read full notes →](2026/2026-05-19-cli-v1-3-4.md)
+
+### Skills · v0.9.1
+**request-session skill now retries preflight on transient catalog errors**
+
+Sessions targeting catalog services no longer fail immediately when the catalog returns a 503 — the skill retries with backoff before surfacing the error.
+
+[Read full notes →](2026/2026-05-19-skills-v0-9-1.md)
+
+### Web · v1.2.0
+**Session approval page shows estimated fees alongside budget cap**
+
+Users approving a new session see an itemized 'up to ~$X' estimate next to the raw budget cap, matching the new backend preflight data.
+
+[Read full notes →](2026/2026-05-19-web-v1-2-0.md)
+<!-- changelog-index-end -->
+
+---
+
+## Editing entries
+
+The changelog action opens a PR for each component release tag. The `<details><summary>Included changes</summary>` block is auto-extracted from commit subjects and should not be hand-edited; the narrative above it is free to edit.
+
+For corrections after publish, set `corrected_at: YYYY-MM-DD` in frontmatter and add an `> **Update YYYY-MM-DD:** ...` admonition at the top of the narrative.

changelog/components.yml

@@ -0,0 +1,24 @@
+components:
+  backend:
+    name: Backend
+    description: |
+      The Kite Passport HTTP API and worker fleet. Handles delegations, session
+      lifecycle, x402 payment negotiation, agent registration, and order
+      orchestration.
+  web:
+    name: Web
+    description: |
+      The Passport dashboard and approval UI at passport.gokite.ai. Where users
+      review and approve agent spending sessions with a passkey.
+  cli:
+    name: CLI
+    description: |
+      The kpass CLI — the primary surface agents use to drive Passport.
+      Provides commands for auth, agents, sessions, payments, wallet, shopping,
+      activity, and self-upgrade.
+  skills:
+    name: Skills
+    description: |
+      The passport-skills SKILL.md bundle that teaches client AI agents
+      (Claude Code, Cursor, Cline, Codex, Windsurf) exactly how to drive
+      kpass and ksearch.