@agent-native/core 0.90.11 → 0.91.0

package/docs/content/toolkit-settings.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Settings Kit"
-description: "A standard settings-page contract for app, agent, provider, team, and language settings."
+description: "A standard, searchable settings-page contract for app, agent, provider, team, and language settings."
 ---
 
 # Settings Kit
@@ -10,11 +10,17 @@ not have to wonder whether model keys live in an app settings page, a giant
 agent sidebar panel, or a provider-specific setup card. The app route owns the
 page; framework tabs can be mounted inside it.
 
+Every settings page is **searchable out of the box**: `<SettingsTabsPage>`
+renders a search box that indexes tabs and their controls, so a user can type
+"language", "S3", or "API key" and jump straight to the right section across any
+tab — no hunting through the nav. This is a core value prop of the kit and comes
+free the moment an app adopts the shared page.
+
 <WireframeBlock id="doc-block-toolkit-settings">
   <Screen
     surface="desktop"
     html={
-      "<div style='min-height:520px;box-sizing:border-box;padding:26px;display:grid;grid-template-columns:200px 1fr;gap:18px'><aside class='wf-card' style='display:flex;flex-direction:column;gap:6px'><strong style='margin-bottom:4px'>Settings</strong><div style='padding:7px 9px;border-radius:8px'>General</div><div style='padding:7px 9px;border-radius:8px;background:var(--wf-accent-soft);display:flex;align-items:center;gap:8px'><span data-icon='settings'></span> AI and models</div><div style='padding:7px 9px;border-radius:8px'>Connections</div><div style='padding:7px 9px;border-radius:8px'>Team</div><div style='padding:7px 9px;border-radius:8px'>Developer</div></aside><main class='wf-card' style='display:flex;flex-direction:column;gap:14px'><h2 style='margin:0'>AI and models</h2><div style='display:flex;flex-direction:column;gap:6px'><small class='wf-muted'>Default model</small><div class='wf-box' style='display:flex;align-items:center;gap:8px'><div style='flex:1'>GPT-5</div><span data-icon='chevronDown'></span></div></div><div style='display:flex;flex-direction:column;gap:8px'><small class='wf-muted'>Provider keys</small><div class='wf-box' style='display:flex;align-items:center;gap:10px'><span data-icon='check'></span><div style='flex:1'>OpenAI</div><span class='wf-pill'>Connected</span></div><div class='wf-box' style='display:flex;align-items:center;gap:10px'><span data-icon='lock'></span><div style='flex:1'>Anthropic</div><button>Add key</button></div><div class='wf-box' style='display:flex;align-items:center;gap:10px'><span data-icon='check'></span><div style='flex:1'>Builder</div><span class='wf-pill'>Connected</span></div></div><div style='flex:1'></div><div style='display:flex;gap:10px'><button>Open agent settings</button><div style='flex:1'></div><button class='primary'>Save changes</button></div></main></div>"
+      "<div style='min-height:520px;box-sizing:border-box;padding:26px;display:grid;grid-template-columns:200px 1fr;gap:18px'><aside class='wf-card' style='display:flex;flex-direction:column;gap:6px'><strong style='margin-bottom:4px'>Settings</strong><div class='wf-box' style='display:flex;align-items:center;gap:8px;margin-bottom:4px'><span data-icon='search'></span><span class='wf-muted'>Search settings</span></div><div style='padding:7px 9px;border-radius:8px'>General</div><div style='padding:7px 9px;border-radius:8px;background:var(--wf-accent-soft);display:flex;align-items:center;gap:8px'><span data-icon='settings'></span> AI and models</div><div style='padding:7px 9px;border-radius:8px'>Connections</div><div style='padding:7px 9px;border-radius:8px'>Team</div><div style='padding:7px 9px;border-radius:8px'>Developer</div></aside><main class='wf-card' style='display:flex;flex-direction:column;gap:14px'><h2 style='margin:0'>AI and models</h2><div style='display:flex;flex-direction:column;gap:6px'><small class='wf-muted'>Default model</small><div class='wf-box' style='display:flex;align-items:center;gap:8px'><div style='flex:1'>GPT-5</div><span data-icon='chevronDown'></span></div></div><div style='display:flex;flex-direction:column;gap:8px'><small class='wf-muted'>Provider keys</small><div class='wf-box' style='display:flex;align-items:center;gap:10px'><span data-icon='check'></span><div style='flex:1'>OpenAI</div><span class='wf-pill'>Connected</span></div><div class='wf-box' style='display:flex;align-items:center;gap:10px'><span data-icon='lock'></span><div style='flex:1'>Anthropic</div><button>Add key</button></div><div class='wf-box' style='display:flex;align-items:center;gap:10px'><span data-icon='check'></span><div style='flex:1'>Builder</div><span class='wf-pill'>Connected</span></div></div><div style='flex:1'></div><div style='display:flex;gap:10px'><button>Open agent settings</button><div style='flex:1'></div><button class='primary'>Save changes</button></div></main></div>"
     }
   />
 </WireframeBlock>
@@ -23,8 +29,9 @@ page; framework tabs can be mounted inside it.
 
 | Piece                    | Purpose                                                                               |
 | ------------------------ | ------------------------------------------------------------------------------------- |
-| `<SettingsTabsPage>`     | Standard tabbed settings route surface.                                               |
+| `<SettingsTabsPage>`     | Standard tabbed settings route surface with a built-in settings search box.           |
 | `useAgentSettingsTabs()` | Framework-provided agent, model, key, automation, and voice tabs that apps can mount. |
+| `SettingsSearchEntry`    | A deep-link target (label, keywords, tab, and hash) that makes a control findable.    |
 | `<LanguagePicker>`       | Standard language selector for app settings.                                          |
 | `openAgentSettings()`    | Compatibility escape hatch for opening the sidebar settings tab when needed.          |
 | Hash deep links          | Stable links such as `/settings#secrets:OPENAI_API_KEY` and `/settings#connections`.  |
@@ -52,10 +59,56 @@ export default function SettingsRoute() {
 }
 ```
 
+## Search {#search}
+
+The search box is enabled by default. With no extra work it matches on tab
+labels, so users can already filter the nav. To make individual controls
+discoverable, register `SettingsSearchEntry` items — each result switches to the
+right tab and scrolls to the target section:
+
+```tsx
+const agentSettingsTabs = useAgentSettingsTabs(); // already ships search entries
+
+return (
+  <SettingsTabsPage
+    extraTabs={[
+      {
+        id: "alerts",
+        label: "Alerts",
+        content: <AlertRulesSettingsCard />,
+        keywords: "notifications thresholds monitors",
+        searchEntries: [
+          { id: "alert-rules", label: "Alert rules", hash: "alert-rules" },
+        ],
+      },
+      ...agentSettingsTabs,
+    ]}
+    general={<LanguagePicker label="Interface language" />}
+    // Deep-link targets that live inside the General tab.
+    generalSearchEntries={[
+      {
+        id: "language",
+        label: "Language",
+        keywords: "locale translation interface",
+        hash: "language",
+      },
+    ]}
+  />
+);
+```
+
+Give each searchable card a matching `id` (e.g. `id="language"`) so the entry's
+`hash` can scroll to it. Add `keywords` for synonyms and provider names the
+label does not contain (e.g. "S3", "R2", "bucket" for replay storage). Set
+`enableSearch={false}` only for trivial single-section pages; prefer keeping it
+on so settings stay findable everywhere.
+
 ## UX Standard {#ux-standard}
 
 - Keep model keys, OAuth connections, Builder connect, language, team, and app
   preferences in one route.
+- Keep search on and register a `SettingsSearchEntry` for every meaningful
+  control so users can find settings by name instead of scanning tabs.
 - Link to tabs by hash so setup prompts can send users to the exact missing
   credential.
 - Use the agent sidebar settings only as a compact access point, not as the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.90.11",
+  "version": "0.91.0",
   "description": "Framework for agent-native application development — where AI agents and UI share SQL state, actions, and context",
   "homepage": "https://github.com/BuilderIO/agent-native#readme",
   "bugs": {
@@ -256,6 +256,7 @@
     "@rrweb/record": "2.0.1",
     "@sentry/browser": "10.60.0",
     "@sentry/node": "10.60.0",
+    "@shadcn/react": "^0.2.0",
     "@standard-schema/spec": "^1.1.0",
     "@tanstack/react-table": "^8.21.3",
     "@tiptap/core": "3.27.1",

package/src/templates/workspace-core/.agents/skills/agent-native-toolkit/SKILL.md

@@ -40,8 +40,10 @@ in the moment of agent use.
 
 ## Reusable Kits
 
-- **Settings kit**: account, workspace, AI models, LLM keys, connections,
-  secrets, usage, notifications, changelog, and app-specific panels.
+- **Settings kit**: a searchable settings page with account, workspace, AI
+  models, LLM keys, connections, secrets, usage, notifications, changelog, and
+  app-specific panels. Search is on by default; register a `SettingsSearchEntry`
+  per control so users find settings by name across tabs.
 - **Collaboration kit**: Yjs docs, presence, agent presence, live cursors,
   remote selections, recent edit highlights, real-time sync indicators, and
   undo/redo grouping.

package/src/templates/workspace-core/.agents/skills/changelog/SKILL.md

@@ -15,8 +15,9 @@ metadata:
 Every template app keeps a `CHANGELOG.md` of **user-facing** changes that
 renders in-app via the command menu (Cmd+K → "What's new") and on the settings
 page. The flow mirrors changesets so it survives many agents working in
-parallel: each change drops a small **pending entry file**, and a later
-**release** rolls all pending files into a dated `CHANGELOG.md` section.
+parallel: each change drops a small **pending entry file**, the in-app surface
+reads pending files plus `CHANGELOG.md`, and a later **release** can roll those
+pending files into dated `CHANGELOG.md` sections.
 
 ## When to add an entry
 
@@ -69,9 +70,10 @@ agent-native changelog release            # uses today's date
 agent-native changelog list               # preview pending + released
 ```
 
-Releasing is usually done at deploy/merge time. The in-app surface reads
-`CHANGELOG.md`, so only released entries are visible to users — pending entries
-stay invisible until rolled up.
+Releasing is usually done at deploy/merge time to keep the source tree tidy.
+The in-app surface imports `CHANGELOG.md?raw`, and the core Vite plugin merges
+adjacent `changelog/*.md` pending entries into that raw markdown at dev/build
+time, so product notes become visible without waiting for a manual rollup.
 
 ## Wiring the in-app surface (once per template)
 
@@ -108,4 +110,5 @@ host with no server route or runtime file access.
 - [ ] Shipped a user-visible change? Run `agent-native changelog add "…"`.
 - [ ] New template UI? Pass `changelog` to its `CommandMenu` and seed a
       `CHANGELOG.md`.
-- [ ] Releasing/deploying? `agent-native changelog release` rolls pending → dated.
+- [ ] Releasing/deploying? Optional: `agent-native changelog release` rolls
+      pending → dated sections and deletes the pending files.