Merge branch 'main' into fix/4726-self-host-db-init

Author: mmabrouk

.agents/skills/write-pr-description/SKILL.md

@@ -39,6 +39,9 @@ Use this shape unless the change is truly trivial:
 
 ## Tests / notes
 <short bullet list or prose: what you verified, anything reviewers should watch for>
+
+## What to QA
+<only for user-visible changes: short steps for the manual tester, see section 7>
 ```
 
 Adapt the headings if the situation calls for it (e.g. a pure feature PR might use "What this adds" instead of "What was broken"). The order stays the same: the obeservation (symptom or user-visible change first or intent), then the changes, then verification and validation.
@@ -102,7 +105,26 @@ Keep this section short and concrete. Useful contents:
 
 Skip the section entirely if there is nothing real to say. A blank "Tests" heading is worse than no heading.
 
-## 7. Reviewer's first-30-seconds test
+## 7. What to QA section
+
+If the change is user-visible and a teammate will test it manually, add a "What to QA" section. Write it for a tester who knows the product and has context: skip the basics, point at the right screens, and state the expected result of every check.
+
+- One line per check: where to go, what to do, what they should see.
+- Name the exact pages and flows. "Test the feature" is not a check.
+- Include the regression to watch for: the thing this change is most likely to have broken.
+- If a check needs setup (a seeded project, an older record, a feature flag), say so in the same line.
+- Use simple, clear language. Same prose rules as section 5.
+
+Example:
+
+> ## What to QA
+> - Create a new automatic evaluator, name it, save. The table shows your name with a v1 tag, not "default".
+> - Edit it and commit a config change. The name stays, the version bumps to v2.
+> - Regression: run a new evaluation. The variant chips still say "default", not the app name.
+
+Skip the section when nothing is user-visible (pure refactor, CI, docs). A reviewer-only change needs the Tests section, not this one.
+
+## 8. Reviewer's first-30-seconds test
 
 Before you finalize, read your own draft and ask:
 
@@ -113,7 +135,7 @@ Before you finalize, read your own draft and ask:
 
 If any answer is no, edit before you push.
 
-## 8. Worked example
+## 9. Worked example
 
 A bad first draft:
 
@@ -147,6 +169,10 @@ After:
 ## Tests
 - Added a unit test in parseToolsFromTrace.test.ts covering both shapes.
 - Opened a real OpenInference trace from the staging project and confirmed the tools panel renders.
+
+## What to QA
+- Open an OpenInference trace in the playground (the staging project has them). The tools panel lists the tools.
+- Regression: open a trace from the OpenAI SDK. The tools panel still renders as before.
 ```
 
 The second version is cleaner and tells the reviewer everything they need to start reading the diff.

.all-contributorsrc

@@ -596,6 +596,52 @@
         "platform",
         "doc"
       ]
+    },
+    {
+      "login": "Sanket2329",
+      "name": "Sanket Shakya",
+      "avatar_url": "https://avatars.githubusercontent.com/u/196506711?v=4",
+      "profile": "https://github.com/Sanket2329",
+      "contributions": [
+        "code"
+      ]
+    },
+    {
+      "login": "unfitcoder101",
+      "name": "unfitcoder101",
+      "avatar_url": "https://avatars.githubusercontent.com/u/175036458?v=4",
+      "profile": "https://github.com/unfitcoder101",
+      "contributions": [
+        "bug"
+      ]
+    },
+    {
+      "login": "Shunmuka",
+      "name": "Shunmuka Valsa",
+      "avatar_url": "https://avatars.githubusercontent.com/u/137101604?v=4",
+      "profile": "https://github.com/Shunmuka",
+      "contributions": [
+        "code",
+        "platform"
+      ]
+    },
+    {
+      "login": "NamHT4Devlop",
+      "name": "Hồ Trung Nam",
+      "avatar_url": "https://avatars.githubusercontent.com/u/122743792?v=4",
+      "profile": "https://github.com/NamHT4Devlop",
+      "contributions": [
+        "code"
+      ]
+    },
+    {
+      "login": "Koushik-Salammagari",
+      "name": "Koushik-Salammagari",
+      "avatar_url": "https://avatars.githubusercontent.com/u/138836560?v=4",
+      "profile": "https://github.com/Koushik-Salammagari",
+      "contributions": [
+        "bug"
+      ]
     }
   ],
   "contributorsPerLine": 7,

.claude/agents/changelog-editor.md

@@ -9,10 +9,17 @@ You are an expert technical documentation editor specializing in Docusaurus chan
 
 ## Your Core Responsibilities
 
-1. **Dual Entry Creation**: For every changelog item, you create two coordinated entries:
-   - A concise summary in `docs/main.mdx`
-   - A detailed explanation in `docs/block/entries/[version-or-feature].mdx`
-   - The summary title must link to the detailed entry
+1. **Entry Creation**: For every changelog item, you create one entry file in
+   `docs/blog/entries/[version-or-feature].mdx`. The changelog index page at
+   `/changelog` is generated automatically from these files (sorted by `date`,
+   paginated). Each entry holds two texts: a curated short summary wrapped in
+   `<Summary>...</Summary>`, then a `{/* truncate */}` marker, then the full
+   write-up. `<Summary>` shows only on the index (as the preview, with a "Read
+   more" link) and renders nothing on the entry page, so the page shows just
+   the full write-up. The short summary can differ from the long write-up's
+   opening; do not just copy its first lines. If the feature has a demo video
+   or screenshot, put it inside `<Summary>` (so it shows on the index) and
+   again in the write-up below the marker (so it shows on the entry page).
 
 2. **Version Management**: Before creating any entry, determine the version number. If unclear from context, ask the user: "Which version is this changelog entry for?" Never proceed without a clear version identifier.
 
@@ -62,8 +69,8 @@ You are an expert technical documentation editor specializing in Docusaurus chan
 
 **Quality Control Checklist (apply to every entry):**
 - [ ] Version number present and correct
-- [ ] Both short and detailed entries created
-- [ ] Short entry links to detailed entry correctly
+- [ ] Entry created in `docs/blog/entries/`
+- [ ] Curated summary in `<Summary>`, then `{/* truncate */}`, then the full write-up
 - [ ] Active voice used where possible
 - [ ] No em dashes present
 - [ ] Feature documentation linked if applicable
@@ -74,10 +81,9 @@ You are an expert technical documentation editor specializing in Docusaurus chan
 ## Output Format
 
 When creating or editing changelog entries, provide:
-1. The complete markdown for the main.mdx summary entry
-2. The complete markdown for the detailed entries/[name].mdx file
-3. Confirmation that you've checked for related documentation
-4. Build test results
-5. Any questions or clarifications needed
+1. The complete markdown for the entries/[name].mdx file
+2. Confirmation that you've checked for related documentation
+3. Build test results
+4. Any questions or clarifications needed
 
 Be proactive in identifying unclear requirements and ask specific questions rather than making assumptions. Your goal is to produce changelog entries that are immediately publishable without requiring revision.

.claude/skills/create-changelog-announcement/SKILL.md

@@ -8,32 +8,57 @@ user-invocable: true
 # Create Changelog Announcement
 
 This skill guides you through creating complete changelog announcements that include:
-1. Detailed changelog documentation page in `/docs/blog/entries/`
-2. Summary entry in `/docs/blog/main.mdx`
-3. Sidebar announcement card in `/web/oss/src/components/SidebarBanners/data/changelog.json`
-4. Roadmap update in `/docs/src/data/roadmap.ts`
-5. GitHub discussion closure (if applicable)
-6. Social media announcements (LinkedIn, Twitter, Slack)
+1. Changelog entry page in `/docs/blog/entries/` (the changelog index at `/changelog` is generated from these automatically, with pagination)
+2. Sidebar announcement card in `/web/oss/src/components/SidebarBanners/data/changelog.json`
+3. Roadmap update in `/docs/src/data/roadmap.ts`
+4. GitHub discussion closure (if applicable)
+5. Social media announcements (LinkedIn, Twitter, Slack)
 
 ## Your Core Responsibilities
 
 ### 1. **Complete Changelog Creation Workflow**
 
-For every changelog announcement, you create THREE coordinated entries:
+For every changelog announcement, you create TWO coordinated artifacts:
 
-**A. Detailed Entry** (`docs/blog/entries/[feature-slug].mdx`):
+**A. Changelog Entry** (`docs/blog/entries/[feature-slug].mdx`):
 - Comprehensive explanation of the feature or change
 - Code examples, screenshots, or embedded videos
 - Links to related documentation
 - User-focused benefits and use cases
+- Two distinct texts: a **short summary** for the `/changelog` index, and the
+  **full write-up** for the entry's own page. The short version is the curated
+  1-2 paragraph summary (it can differ from the long version's opening; do not
+  just copy the first lines of the long write-up). Structure the file as:
 
-**B. Summary Entry** (`docs/blog/main.mdx`):
-- Concise 1-2 paragraph summary
-- Version number and date
-- Link to detailed entry
-- Embedded media if significant feature
+  ```mdx
+  ---frontmatter---
 
-**C. Sidebar Announcement** (`web/oss/src/components/SidebarBanners/data/changelog.json`):
+  import Image from "@theme/IdealImage"; {/* only if you use <Image> */}
+
+  <Summary>
+
+  {/* Optional hero video or screenshot, shown on the index */}
+
+  Curated 1-2 paragraph summary shown on the /changelog index.
+
+  </Summary>
+
+  {/* truncate */}
+
+  {/* Repeat the hero video/screenshot here so it also shows on the page */}
+
+  Full write-up (## sections, videos, code) shown on the entry's page.
+  ```
+
+  `<Summary>` renders only on the index list (as the preview, with a "Read
+  more" link); it renders nothing on the entry page, so the page shows just the
+  full write-up with no duplication. If the feature has a demo video or
+  screenshot, put it inside `<Summary>` so it appears on the index, and also in
+  the write-up below the marker so it appears on the entry page. Embedded
+  videos and images are capped to a centered 680px in CSS, so use the existing
+  `<iframe>`/`<Image>` markup as-is.
+
+**B. Sidebar Announcement** (`web/oss/src/components/SidebarBanners/data/changelog.json`):
 - One-sentence description
 - Link to detailed documentation
 - Unique ID with date
@@ -82,7 +107,7 @@ Apply these writing guidelines rigorously:
 
 **Version Format**:
 - Use semantic versioning: `v0.73.0`
-- Include in summary entry
+- Include it as the entry's tag (`tags: [v0.73.0]`); the changelog index shows it as a version chip next to the date
 
 ### 5. **Media Handling**
 
@@ -132,8 +157,8 @@ Apply these writing guidelines rigorously:
 
 Before finalizing, verify:
 - [ ] Version number present and correct
-- [ ] All three entries created (detailed, summary, sidebar)
-- [ ] Summary links to detailed entry correctly
+- [ ] Entry and sidebar announcement created
+- [ ] Curated summary wrapped in `<Summary>`, then `{/* truncate */}`, then the full write-up
 - [ ] Active voice used where possible
 - [ ] No em dashes present
 - [ ] Feature documentation linked if applicable
@@ -144,13 +169,12 @@ Before finalizing, verify:
 
 ### 8. **File Locations Reference**
 
-**Detailed changelog entries:**
+**Changelog entries:**
 - Path: `/docs/blog/entries/[feature-slug].mdx`
 - Example: `/docs/blog/entries/chat-sessions-observability.mdx`
-
-**Summary changelog:**
-- Path: `/docs/blog/main.mdx`
-- Add new entry at the TOP of the file (after imports, before other entries)
+- The changelog index page at `/changelog` is built automatically from these
+  files (sorted by `date`, paginated). There is no separate summary file to
+  maintain.
 
 **Sidebar announcements:**
 - Path: `/web/oss/src/components/SidebarBanners/data/changelog.json`
@@ -189,9 +213,14 @@ description: "One-sentence description of the feature."
 
 {/* NOTE: Do NOT add an H1 heading here. The frontmatter title is automatically rendered as H1 by Docusaurus. */}
 
-## Overview
+<Summary>
+
+[Curated 1-2 paragraph summary. This is the SHORT version shown on the
+/changelog index. It can differ from the long write-up's opening.]
 
-[2-3 paragraphs explaining what this feature is and why it matters]
+</Summary>
+
+{/* truncate */}
 
 ## Key Capabilities
 
@@ -225,22 +254,20 @@ ag.tracing.store_session(session_id="conversation_123")
 [Optional: What's coming next or related features]
 ```
 
-### Step 4: Add Summary to main.mdx
-Add to `/docs/blog/main.mdx` at the TOP (after imports):
-
-```mdx
-### [Feature Name](/changelog/feature-slug)
+### Step 4: Write the Summary and Place the Truncate Marker
 
-_DD Month YYYY_
+The `/changelog` index shows the `<Summary>` block (with a "Read more" link);
+the entry page shows everything below `{/* truncate */}`. So:
 
-**vX.Y.Z**
-
-[1-2 paragraph summary explaining what the feature does and why users should care. Focus on benefits and capabilities.]
-
-[Optional: Add embedded video or image if this is a major feature]
-
----
-```
+- Put the curated short summary inside `<Summary>...</Summary>`, then the
+  `{/* truncate */}` marker, then the full write-up.
+- Leave blank lines inside the `<Summary>` tags so the content parses as
+  Markdown (links and bold work).
+- If there is a demo video or screenshot, include it inside `<Summary>` (so it
+  shows on the index) and again in the write-up below the marker (so it shows
+  on the entry page).
+- Every entry needs content below the marker (the full write-up); that is what
+  the entry page renders.
 
 ### Step 5: Add Sidebar Announcement
 Add to `/web/oss/src/components/SidebarBanners/data/changelog.json`:
@@ -406,21 +433,6 @@ Learn more in our documentation:
 We're continuing to enhance session tracking with upcoming features like session-level annotations, session comparisons, and automated session analysis.
 ```
 
-**Summary Entry** (add to `docs/blog/main.mdx`):
-```mdx
-### [Chat Sessions in Observability](/changelog/chat-sessions-observability)
-
-_9 January 2026_
-
-**v0.73.0**
-
-You can now track multi-turn conversations with chat sessions. All traces with the same session ID are automatically grouped together, letting you analyze complete conversations instead of individual requests.
-
-The new session browser shows key metrics like total cost, latency, and token usage per conversation. Open any session to see all traces with their parent-child relationships. This makes debugging chatbots and AI assistants much easier. Add session tracking with one line of code using either our Python SDK or OpenTelemetry.
-
----
-```
-
 **Sidebar Announcement**:
 ```json
 {
@@ -463,21 +475,20 @@ The new session browser shows key metrics like total cost, latency, and token us
 
 When creating a changelog announcement, provide:
 
-1. **Detailed entry content** for `docs/blog/entries/[slug].mdx`
-2. **Summary entry content** to add to `docs/blog/main.mdx`
-3. **Sidebar announcement JSON** to add to `changelog.json`
-4. **Confirmation** that you checked for related documentation
-5. **Any questions** or clarifications needed
+1. **Entry content** for `docs/blog/entries/[slug].mdx` (curated summary in `<Summary>`, then `{/* truncate */}`, then the full write-up)
+2. **Sidebar announcement JSON** to add to `changelog.json`
+3. **Confirmation** that you checked for related documentation
+4. **Any questions** or clarifications needed
 
 **Be proactive** in identifying unclear requirements. Ask specific questions rather than making assumptions. Your goal is to produce changelog entries that are immediately publishable without requiring revision.
 
 ## Tips for Success
 
-1. **Read existing entries first**: Before creating new entries, read 2-3 recent entries in `main.mdx` and `entries/` to match the tone and structure
+1. **Read existing entries first**: Before creating new entries, read 2-3 recent entries in `entries/` to match the tone and structure
 2. **Be concise**: Users skim changelogs. Front-load the benefit in every sentence.
 3. **Link generously**: Help users find more information easily
 4. **Test your work**: Read the entries out loud to catch awkward phrasing
-5. **Consistency matters**: Ensure terminology matches across all three entries
+5. **Consistency matters**: Ensure terminology matches between the entry and the sidebar announcement
 
 ---