docs: updates docs for prompts plugin

[roroghost17]

Summary

Updates the Prompts plugin to use standardized x-bf- prefixed headers and improves documentation clarity around parameter merging, streaming behavior, and observability integration.

Changes

• Changed prompt plugin headers from bf-prompt-id/bf-prompt-version to x-bf-prompt-id/x-bf-prompt-version for consistency
• Clarified that streaming is controlled entirely by client requests, not merged from committed versions
• Added documentation for prompt tracking in observability logs (name, version, ID)
• Enhanced playground documentation to describe the collapsible settings panel sections
• Improved Go SDK documentation with PromptResolver interface details and context key information
• Updated all code examples and curl commands to use the new header names

Type of change

• Bug fix
• Feature
• Refactor
• Documentation
• Chore/CI

Affected areas

• Core (Go)
• Transports (HTTP)
• Providers/Integrations
• Plugins
• UI (React)
• Docs

How to test

Test the updated prompt plugin headers:

# Test with new headers
curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "x-bf-prompt-id: YOUR-PROMPT-UUID" \
  -H "x-bf-prompt-version: 4" \
  -H "x-bf-vk: sk-bf-your-virtual-key" \
  -d '{"model": "openai/gpt-4", "messages": [{"role": "user", "content": "Hello"}]}'

# Verify observability logs capture prompt tracking information
# Check that logs show Selected Prompt name, version, and ID

# Core/Transports
go version
go test ./...

Verify that the old bf-prompt-id headers no longer work and the new x-bf-prompt-id headers function correctly.

Screenshots/Recordings

N/A

Breaking changes

• Yes
• No

Breaking change: The prompt plugin now requires x-bf-prompt-id and x-bf-prompt-version headers instead of bf-prompt-id and bf-prompt-version.

Migration: Update all client code to use the new header names:

• bf-prompt-id → x-bf-prompt-id
• bf-prompt-version → x-bf-prompt-version

Related issues

N/A

Security considerations

Header name changes do not introduce security implications. The functionality remains the same with standardized naming.

Checklist

• I read docs/contributing/README.md and followed the guidelines
• I added/updated tests where appropriate
• I updated documentation where needed
• I verified builds succeed (Go and UI)
• I verified the CI pipeline passes locally if applicable

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 80210513-3fad-44c4-aeee-ed78a9e76ad9

📥 Commits

Reviewing files that changed from the base of the PR and between aa3b9fe and 9a5e8bb.

📒 Files selected for processing (4)

• docs/features/observability/default.mdx
• docs/features/prompt-repository/playground.mdx
• docs/features/prompt-repository/prompts-plugin.mdx
• plugins/prompts/changelog.md

✅ Files skipped from review due to trivial changes (3)

• plugins/prompts/changelog.md
• docs/features/observability/default.mdx
• docs/features/prompt-repository/playground.mdx

🚧 Files skipped from review as they are similar to previous changes (1)

• docs/features/prompt-repository/prompts-plugin.mdx

---

📝 Walkthrough

Summary by CodeRabbit

• Documentation
  • Updated prompt plugin docs and changelog to reflect flow and header updates
  • Clarified prompt resolution and resolver guidance, including version-selection semantics
  • Clarified streaming behavior and that client-supplied model parameters take precedence
  • Expanded Playground settings with a Deployments section and collapsible configuration groups
• Logging
  • Enhanced logs to show the selected prompt’s name, version and ID when the Prompts plugin is active

Walkthrough

Documentation updates for the Prompts plugin and Playground UI: header names changed to x-bf-*; clarified prompt version resolution and client-controlled streaming; documented merged model-parameter precedence and PromptResolver API; added selected-prompt metadata to observability logs; expanded Settings panel docs to include Deployments.

Changes

Cohort / File(s)	Summary
Observability docs docs/features/observability/default.mdx	Added Prompt Tracking entry to Request Data logs: logs now include selected prompt name, version, and ID when Prompts plugin is active.
Playground / Settings docs docs/features/prompt-repository/playground.mdx	Expanded Settings panel description to include Deployments and clarified panel is split into collapsible sections: Configuration and Deployments.
Prompts plugin docs docs/features/prompt-repository/prompts-plugin.mdx	Replaced bf-prompt-id/bf-prompt-version with x-bf-prompt-id/x-bf-prompt-version across examples and Go SDK keys; clarified version-resolution (0 → latest committed), client-controlled streaming via request-body "stream": true, merged model-parameter precedence (request wins), updated provider/logging behavior, and added PromptResolver interface details and additional context keys set after injection.
Changelog plugins/prompts/changelog.md	Added changelog entry describing prompt plugin refactor and header-name updates.

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant PromptsPlugin as "Prompts Plugin"
  participant Provider
  participant Logs

  Client->>PromptsPlugin: HTTP request (headers: `x-bf-prompt-id`?, `x-bf-prompt-version`?, body includes "stream"?, model params)
  PromptsPlugin->>PromptsPlugin: resolve prompt (version header or versionNumber 0 => latest committed)
  PromptsPlugin->>PromptsPlugin: merge committed prompt model params with request params (request wins)
  PromptsPlugin->>Provider: forward injected messages + merged params (transport streaming controlled by Client "stream")
  Provider-->>Client: model response (stream or non-stream)
  PromptsPlugin->>Logs: emit conversation + selected prompt metadata (name, id, version)

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐰 I nibbled headers, bf- hopped to x-,
Streams now follow the client's soft flex,
Parameters mingle, the request takes lead,
Prompts logged with names and versions indeed,
Deployments peek out — a carroted new scene!

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and accurately summarizes the main change—documentation updates for the prompts plugin—though it could be more specific.
Description check	✅ Passed	The PR description is comprehensive and well-structured, following the template with clear summary, detailed changes, proper type/area selection, testing instructions, and breaking change documentation.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch 04-16-docs_updates_docs_for_prompts_plugin

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[roroghost17]

• docs: updates docs for prompts plugin #2763 👈 (View in Graphite)
• feat: wires prompt plugin selections into logs view #2592
• refactor: updates prompt model parameters UI #2548
• feat: updates prompts plugin flow #2545
• refactor: Extracts routing utilites to a separate package #2544
• feat: add prompt deployment view to settings panel with updated styling #2352
• refactor: deleted subpages from the prompt repo #2327
• refactor: extract CEL rule builder into reusable component and add menu portal support #2237 : 1 other dependent PR (#2234 )
• feat: add variables support to prompt sessions and versions with database migration #2154
• feat: add variables support to prompt sessions and versions with persistence #2134
• v1.5.0

This stack of pull requests is managed by Graphite. Learn more about stacking.

[greptile-apps]

Confidence Score: 5/5

Safe to merge — all changes are documentation only and accurately reflect the current codebase.

All four changed files are documentation or a changelog entry. The header names, streaming behavior description, and context key names were verified against the current plugins/prompts/main.go source and are accurate. No P0 or P1 findings; the only open concerns (stale screenshot alt text, missing trailing newline) were already raised in prior review threads.

No files require special attention.

Important Files Changed

Filename	Overview
docs/features/prompt-repository/prompts-plugin.mdx	Headers updated from bf- to x-bf- prefix throughout, streaming section rewritten to reflect client-controlled streaming, observability context keys documented; accurate against source code.
docs/features/observability/default.mdx	Adds Prompt Tracking bullet to the Request Data section, accurately reflecting the context keys set by the prompts plugin.
docs/features/prompt-repository/playground.mdx	Adds description of the collapsible settings panel sections (Configuration and Deployments); minimal, accurate change.
plugins/prompts/changelog.md	Single changelog entry for the prompts plugin header refactor; no trailing newline (pre-existing concern already flagged).

_{Reviews (5): Last reviewed commit: "docs: updates docs for prompts plugin" | Re-trigger Greptile}

[coderabbitai]

🧹 Nitpick comments (1)

plugins/prompts/changelog.md (1)

1-1: Consider noting the breaking change nature in the changelog.

The PR objectives describe this as a breaking change requiring clients to migrate from bf-prompt-id → x-bf-prompt-id and bf-prompt-version → x-bf-prompt-version. A changelog entry typically benefits from explicitly flagging breaking changes for users scanning release notes.

📝 Suggested enhancement

-- refactor: Updates prompt plugin flow to change the headers used, and better code quality
+- **BREAKING**: Updates prompt plugin flow to use `x-bf-prompt-id` / `x-bf-prompt-version` headers (previously `bf-prompt-id` / `bf-prompt-version`), and improves code quality

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@plugins/prompts/changelog.md` at line 1, Update the changelog entry (the
refactor line) to explicitly mark this as a BREAKING CHANGE and list the header
renames: clients must migrate from bf-prompt-id → x-bf-prompt-id and
bf-prompt-version → x-bf-prompt-version; mention any migration notes or examples
to help users update clients and surface the breaking-change label prominently
so it’s visible to readers scanning release notes.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@plugins/prompts/changelog.md`:
- Line 1: Update the changelog entry (the refactor line) to explicitly mark this
as a BREAKING CHANGE and list the header renames: clients must migrate from
bf-prompt-id → x-bf-prompt-id and bf-prompt-version → x-bf-prompt-version;
mention any migration notes or examples to help users update clients and surface
the breaking-change label prominently so it’s visible to readers scanning
release notes.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 2b795f1b-5a0a-435a-b877-a9510db25968

📥 Commits

Reviewing files that changed from the base of the PR and between 3fa3852 and aded03a.

📒 Files selected for processing (4)

• docs/features/observability/default.mdx
• docs/features/prompt-repository/playground.mdx
• docs/features/prompt-repository/prompts-plugin.mdx
• plugins/prompts/changelog.md

[akshaydeo]

Merge activity

• Apr 16, 4:34 PM UTC: A user started a stack merge that includes this pull request via Graphite.
• Apr 16, 4:47 PM UTC: @akshaydeo merged this pull request with Graphite.

The base branch was changed.