@raybase/guide 0.0.1 → 0.1.2

package/dist/runtime.js

@@ -0,0 +1,136 @@
+import { corpusSearchSource, defineRaybaseModule, defineSearchIndex, mergeRaybaseSearch, raybaseSupportRequestsTableName } from "@raybase/core";
+import { guideActions, guideAgent, guideAgentSurfaces, guideAudienceFromConfig, normalizeGuideConfig } from "./guide.js";
+import { guideFailuresTableName, raybaseGuideSystemTables } from "./guide-tables.js";
+const guideSearchIndexName = "guide";
+export function guideModule(options = {}) {
+    return defineRaybaseModule({
+        id: "guide",
+        packageName: "@raybase/guide",
+        runtime: (ctx) => guideRuntime(ctx, options)
+    });
+}
+export function guideRuntime(ctx, options) {
+    const config = normalizeGuideConfig({ ...(options.config ?? {}), endpoint: options.endpoint ?? options.config?.endpoint, agent: { ...(options.config?.agent ?? {}), ...(options.agent ?? {}) } });
+    if (!config.enabled) {
+        return {
+            agentSurfaces: guideAgentSurfaces(config),
+            manifest: {
+                id: "guide",
+                packageName: "@raybase/guide",
+                guide: {
+                    enabled: false,
+                    agentName: config.agent.name,
+                    mode: "implicit",
+                    hasExplicitCorpus: false,
+                    corpusDocumentCount: 0,
+                    actionNames: [],
+                    explicitActionNames: []
+                }
+            }
+        };
+    }
+    const search = searchWithGuideCorpus(options.corpus);
+    const actionSearch = mergeRaybaseSearch(ctx.search, search);
+    const actions = guideActions({
+        config,
+        schema: ctx.schema,
+        search: actionSearch,
+        retrieval: ctx.retrieval,
+        actions: options.actions
+    });
+    const explicitActionNames = (options.actions ?? []).map((action) => action.name);
+    return {
+        systemTables: raybaseGuideSystemTables,
+        agents: {
+            [config.agent.name]: guideAgent({
+                name: config.agent.name,
+                audience: guideAudienceFromConfig(config),
+                corpus: options.corpus,
+                actions,
+                title: config.agent.title,
+                model: config.agent.model,
+                maxOutputTokens: config.agent.maxOutputTokens,
+                limits: config.limits
+            })
+        },
+        search,
+        adminRoutes: [
+            {
+                method: "GET",
+                path: "/api/admin/guide/support-requests",
+                handle: async (routeCtx) => {
+                    routeCtx.requireAdmin();
+                    const url = new URL(routeCtx.request.url);
+                    const limit = Math.min(Number(url.searchParams.get("limit") ?? 100), 500);
+                    const rows = routeCtx.organizationId
+                        ? await routeCtx.control.all(`SELECT * FROM "${raybaseSupportRequestsTableName}" WHERE "sourceKind" = 'guide' AND "organizationId" = ? ORDER BY "updatedAt" DESC LIMIT ?`, [routeCtx.organizationId, limit])
+                        : await routeCtx.control.all(`SELECT * FROM "${raybaseSupportRequestsTableName}" WHERE "sourceKind" = 'guide' ORDER BY "updatedAt" DESC LIMIT ?`, [limit]);
+                    return routeCtx.json({ supportRequests: rows, organizationId: routeCtx.organizationId ?? null });
+                }
+            },
+            {
+                method: "GET",
+                path: "/api/admin/guide/failures",
+                handle: async (routeCtx) => {
+                    routeCtx.requireAdmin();
+                    const url = new URL(routeCtx.request.url);
+                    const limit = Math.min(Number(url.searchParams.get("limit") ?? 100), 500);
+                    const rows = routeCtx.organizationId
+                        ? await routeCtx.control.all(`SELECT * FROM "${guideFailuresTableName}" WHERE "organizationId" = ? ORDER BY "createdAt" DESC LIMIT ?`, [routeCtx.organizationId, limit])
+                        : await routeCtx.control.all(`SELECT * FROM "${guideFailuresTableName}" ORDER BY "createdAt" DESC LIMIT ?`, [limit]);
+                    return routeCtx.json({ failures: rows, organizationId: routeCtx.organizationId ?? null });
+                }
+            }
+        ],
+        agentSurfaces: guideAgentSurfaces(config),
+        manifest: {
+            id: "guide",
+            packageName: "@raybase/guide",
+            guide: {
+                enabled: true,
+                agentName: config.agent.name,
+                mode: options.mode ?? (explicitActionNames.length ? "actions" : "implicit"),
+                hasExplicitCorpus: options.corpus !== undefined,
+                corpusDocumentCount: options.corpus?.length ?? 0,
+                actionNames: actions.map((action) => action.name),
+                explicitActionNames
+            }
+        }
+    };
+}
+function searchWithGuideCorpus(corpus) {
+    if (!corpus?.length)
+        return undefined;
+    return {
+        indexes: {
+            [guideSearchIndexName]: defineSearchIndex({
+                name: guideSearchIndexName,
+                title: "App help",
+                description: "Docs and app help knowledge",
+                sources: [
+                    corpusSearchSource("guide", {
+                        title: "App help",
+                        documents: () => guideCorpusSearchDocuments(corpus)
+                    })
+                ]
+            })
+        }
+    };
+}
+function guideCorpusSearchDocuments(corpus) {
+    return corpus.map((document) => ({
+        id: document.id,
+        title: document.title,
+        body: document.text,
+        url: document.url ?? null,
+        version: document.updatedAt ?? null,
+        public: document.public === true,
+        metadata: {
+            ...(document.metadata ?? {}),
+            guideContext: document.guideContext,
+            source: document.source,
+            routePatterns: document.routePatterns ?? []
+        }
+    }));
+}
+//# sourceMappingURL=runtime.js.map

package/dist/runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,16 +1,57 @@
 {
   "name": "@raybase/guide",
-  "version": "0.0.1",
-  "description": "Reserved for Raybase. Nothing is released under this name yet.",
-  "license": "UNLICENSED",
+  "version": "0.1.2",
+  "description": "First-party Raybase Guide module for end-user app and docs assistance.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./client": {
+      "types": "./dist/guide-client.d.ts",
+      "default": "./dist/guide-client.js"
+    },
+    "./corpus": {
+      "types": "./dist/guide-corpus.d.ts",
+      "default": "./dist/guide-corpus.js"
+    },
+    "./install": {
+      "types": "./dist/install.d.ts",
+      "default": "./dist/install.js"
+    },
+    "./cli": {
+      "types": "./dist/cli.d.ts",
+      "default": "./dist/cli.js"
+    }
+  },
+  "files": [
+    "dist",
+    "templates"
+  ],
+  "peerDependencies": {
+    "zod": "^4.4.3",
+    "@raybase/core": "0.3.3"
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "^4.20260609.0",
+    "typescript": "^5.8.3",
+    "zod": "^4.4.3",
+    "@raybase/core": "0.3.3"
+  },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/raybasedev/raybase.git"
+    "url": "git+https://github.com/raybasedev/raybase.git",
+    "directory": "packages/guide"
   },
   "publishConfig": {
     "access": "public"
   },
-  "files": [
-    "README.md"
-  ]
-}
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "check": "tsc -p tsconfig.json --noEmit"
+  }
+}

package/templates/astro-emdash/content/guide/capability-map.md

@@ -0,0 +1,17 @@
+---
+title: What Guide can do in this app
+guideContext: app-capability-map
+public: false
+---
+
+Guide should answer from the checked-in app docs, help knowledge, and explicit Agent actions registered by the app.
+
+It can explain where to go, how common site editing workflows work, what the current user is allowed to do, and which tasks it can help perform.
+
+For the Astro/EmDash starter, Guide should help editors open the CMS, find pages, edit reusable sections, preview changes, publish safely, connect approved assistants, and know when to ask the project maintainer for a new page section or layout.
+
+Guide should not claim it can publish, delete, or restructure content unless the app registers an explicit action for that task.
+
+When the app registers Agent actions, Guide may use those actions only after the user clearly asks and the action policy allows it. If no action is registered for a task, it can explain the workflow but should not claim it can perform the task.
+
+Guide should not expose raw tool names, internal errors, JSON, SQL, source-code details, platform settings, or implementation jargon. If context is missing or a tool fails, it should respond plainly, offer a useful next step, and ask one clarifying question only when needed.

package/templates/astro-emdash/src/components/guide-widget.tsx

@@ -0,0 +1,41 @@
+import { useRouter } from "@tanstack/react-router";
+import { RaybaseAgentWidget } from "@raybase/agent-ui";
+import { useEffect } from "react";
+import { guideConfig } from "../guide/config";
+
+export function GuideWidget() {
+  const router = useRouter();
+
+  useEffect(() => {
+    const refreshData = () => {
+      void router.invalidate();
+    };
+    window.addEventListener("raybase:data-changed", refreshData);
+    return () => window.removeEventListener("raybase:data-changed", refreshData);
+  }, [router]);
+
+  return (
+    <RaybaseAgentWidget
+      agentName={guideConfig.agent?.name ?? "guide"}
+      enabled={guideConfig.enabled ?? true}
+      isSurfaceEnabled={isGuideSurfaceEnabled}
+      resolveSurface={resolveGuideSurface}
+      title={guideConfig.agent?.title ?? "Guide"}
+    />
+  );
+}
+
+type GuideSurface = "app" | "docs";
+
+function resolveGuideSurface(route: string): GuideSurface {
+  return route.startsWith("/docs") ? "docs" : "app";
+}
+
+function isGuideSurfaceEnabled(surface: string): boolean {
+  if (!isGuideSurface(surface)) return false;
+  return guideConfig.surfaces?.[surface]?.enabled ?? surface === "app";
+}
+
+function isGuideSurface(surface: string): surface is GuideSurface {
+  return surface === "app" || surface === "docs";
+}

package/templates/astro-emdash/src/guide/actions.ts

@@ -0,0 +1,8 @@
+import type { RaybaseAction } from "@raybase/core/actions";
+import type { RaybaseEnv } from "@raybase/core/worker";
+import { actions } from "../actions";
+
+// Keep Guide on a narrow allow-list of app-declared actions.
+export const guideActions = [
+  actions.contentSiteSnapshot
+] satisfies Array<RaybaseAction<any, any, RaybaseEnv>>;

package/templates/astro-emdash/src/guide/config.ts

@@ -0,0 +1,21 @@
+import type { GuideConfig } from "@raybase/guide";
+
+export const guideConfig = {
+  enabled: true,
+  surfaces: {
+    app: { enabled: true, audience: "signed-in" },
+    docs: { enabled: true, audience: "signed-in" }
+  },
+  agent: {
+    name: "guide",
+    title: "Guide"
+  },
+  limits: {
+    publicIpHourlyRequests: 20,
+    publicIpHourlyOutputTokens: 12000,
+    publicDailyRequests: 200,
+    publicDailyOutputTokens: 60000,
+    signedInDailyRequests: 50,
+    maxCorpusSnippets: 8
+  }
+} satisfies GuideConfig;

package/templates/astro-emdash/src/guide/corpus.gen.ts

@@ -0,0 +1,4 @@
+import type { GuideCorpusDocument } from "@raybase/guide";
+import manifest from "./corpus.manifest.json";
+
+export const generatedGuideCorpus = manifest.documents as GuideCorpusDocument[];

package/templates/astro-emdash/src/guide/corpus.manifest.json

@@ -0,0 +1,72 @@
+{
+  "schemaVersion": 1,
+  "generatedAt": "2026-11-14T04:05:39.782Z",
+  "sources": [
+    {
+      "kind": "docs",
+      "path": "content/docs"
+    }
+  ],
+  "documents": [
+    {
+      "id": "docs:content/docs:getting-started.mdx",
+      "title": "Opening the CMS",
+      "source": "docs",
+      "text": "Sign in with the account your team gave you, then open the public site and choose CMS from the signed in menu. Start with Pages. Open an existing draft to review the editing pattern, or create a page when you need a new public URL. Use the page content field to arrange reusable sections. Each section owns its own copy, media, links, and display options. Preview before publishing. If a page needs a new reusable section or a layout change, note the goal clearly and ask the project maintainer to add the building block. Local time travel In local development, use the fixed dev chrome or POST /api/dev/time with \"now\":\"2030 08 12T09:00:00.000Z\" to move the application clock. GET /api/dev/time reports virtual and real time; \"reset\":true returns to wall time. Forward jumps start bounded catch up for Jobs, Agent schedules, wakes, and follow ups. Repeating schedules coalesce to one run, while one shot work drains without waiting for the HTTP response. Auth, leases, retries, tokens, provider calls, and diagnostics remain on real time. Moving backward or resetting does not rewrite future dated rows; reset and reseed when a QA scenario crosses that edge. Local tooling can restore the spine's base world with POST /api/dev/seed and \"reset\":true or apply one named variant with \"variant\":\"empty spine\" . Reset is destructive for spine app tables; use sequential calls to layer variants, and use restore after time travel leaves future dated rows. Content site demo data remains owned by site/ . GET /api/dev/manifest serves the same validated manifestVersion: 1 checkpoint written to .raybase/app.manifest.json at dev startup. Route sources use project relative POSIX paths. Restart raybase dev after changing routes or declarations. The endpoint is local only.",
+      "url": "/docs/getting-started",
+      "routePatterns": [
+        "/docs/getting-started",
+        "/docs/getting-started/*"
+      ],
+      "public": false,
+      "guideContext": null,
+      "updatedAt": "2026-11-14T04:05:26.116Z",
+      "hash": "sha256:6aec1b2e381585c532b62df227dd807aef7dbf91fe71d1f804a05e7793ce36ae"
+    },
+    {
+      "id": "docs:content/docs:index.mdx",
+      "title": "Editing the site",
+      "source": "docs",
+      "text": "The CMS is where signed in editors manage public site pages, drafts, media, and reusable page sections. Use the CMS link in the signed in site menu to open the editing workspace. If the link is not visible, ask the person who manages access to invite you or adjust your role. Most pages are built from a title, slug, metadata, and a sequence of reusable sections. Edit copy and media in the CMS, preview changes, then publish when the page is ready. Keep structural changes deliberate. If you need a new section type, navigation pattern, layout, or data backed block, ask the project maintainer to add it safely.",
+      "url": "/docs",
+      "routePatterns": [
+        "/docs",
+        "/docs/*"
+      ],
+      "public": false,
+      "guideContext": null,
+      "updatedAt": "2026-11-14T04:05:26.115Z",
+      "hash": "sha256:cee1dfcd47c0cc800581e7557c206d725f783ebcab122825455ada421faf13b4"
+    },
+    {
+      "id": "docs:content/docs:mcp.mdx",
+      "title": "Connecting an assistant",
+      "source": "docs",
+      "text": "Some apps let signed in members connect an approved AI assistant through the app's /mcp endpoint. Only connect assistants you trust. The assistant should explain what it can read or change before you approve a task. If the connection fails, confirm you are signed in and ask the project maintainer whether assistant access is enabled for your role.",
+      "url": "/docs/mcp",
+      "routePatterns": [
+        "/docs/mcp",
+        "/docs/mcp/*"
+      ],
+      "public": false,
+      "guideContext": null,
+      "updatedAt": "2026-11-14T04:05:26.116Z",
+      "hash": "sha256:9b7a64f4ce851af9f6664b4de67c6d92c4770228e76f06b3916f050d4b2f6467"
+    },
+    {
+      "id": "docs:content/docs:site-templates.mdx",
+      "title": "Reusable sections",
+      "source": "docs",
+      "text": "Templates are reusable Liquid templates for the public content site. Use them when a template fits the page section, layout, or page starter you need and the result should stay editable in the CMS. Discovery works from any directory: Installed templates are staged under site/seed/templates/ / : template.json is the draft Galley template payload. sample content.json carries registry sample data for review. page starters are Liquid templates that compose their sections with % render % tags; they also stage a page seed under site/seed/pages/ .json that points the page's design field at the starter. optional behavior sidecars are copied beside the staged payload when a template declares one. provenance.json records source URLs, generated hashes, dependencies, bindings, and install choices. Packs that read an EmDash collection through galley.dataSources use their manifest default collection when one is declared. Override or provide a required collection with bind : Theme manifests group a family's voice and vocabulary: palettes, sections, and page starter choices. A theme install stages the required dependencies plus the choices you select: palette is required when a theme lists more than one palette. page stages an EmDash page from a theme page starter key or exact template id. Use all optional only when you intentionally want every optional dependency staged. The site's structure is a shell: a layout with its welded nav and footer, selected by the site plan's capacity needs rather than by theme membership. raybase templates shell match nav items 5 footer links 12 theme raybase/lumen studio filters shells that fit and ranks them by voice fit. For one page sites, add anchor to filter to anchor tuned brand bar shells ( nav items 0 is valid — the logo block still renders at zero links). Then stage the chosen shell: activate stages an ephemeral activation.json work order beside the selected layout; during apply, selected templates are published, the active Galley layout pointer (and palette) is updated in the app database, and the work order is deleted. With the Astro/EmDash dev server running, apply staged templates: Without activate , templates are installed as draft templates. Structural pages point their design field at a page starter template; prose pages keep Portable Text in pages.content , where inline galley.block or galley.shared embeds are still supported. With shell add activate , templates:apply publishes the selected shell and section templates, upserts staged page seeds, and activates the layout for public rendering. Review staged JSON before apply and commit .raybase/templates.json , site/seed/templates/ , and site/seed/pages/ . The visual editor edits copy, fields, rich text, and Portable Text content. Page structure lives in Liquid: page starters compose sections with % render % tags, and structural changes remain agent/code work in Galley templates, resolved by installation (bare template ids, no per reference version pins).",
+      "url": "/docs/site-templates",
+      "routePatterns": [
+        "/docs/site-templates",
+        "/docs/site-templates/*"
+      ],
+      "public": false,
+      "guideContext": null,
+      "updatedAt": "2026-11-14T04:05:26.116Z",
+      "hash": "sha256:9799eff846de2718833130cbdeda6309a584705c1a536fbe95647c7596fef05f"
+    }
+  ]
+}

package/templates/astro-emdash/src/guide/corpus.ts

@@ -0,0 +1,4 @@
+import type { GuideCorpusDocument } from "@raybase/guide";
+import { generatedGuideCorpus } from "./corpus.gen";
+
+export const guideCorpus = generatedGuideCorpus satisfies GuideCorpusDocument[];

package/templates/astro-emdash/src/guide/resources.json

@@ -0,0 +1,4 @@
+{
+  "schemaVersion": 1,
+  "resources": []
+}

package/templates/react-router/app/components/guide-widget.tsx

@@ -0,0 +1,29 @@
+import { RaybaseAgentWidget } from "@raybase/agent-ui";
+import { guideConfig } from "../guide/config";
+
+export function GuideWidget() {
+  return (
+    <RaybaseAgentWidget
+      agentName={guideConfig.agent?.name ?? "guide"}
+      enabled={guideConfig.enabled ?? true}
+      isSurfaceEnabled={isGuideSurfaceEnabled}
+      resolveSurface={resolveGuideSurface}
+      title={guideConfig.agent?.title ?? "Guide"}
+    />
+  );
+}
+
+type GuideSurface = "app" | "docs";
+
+function resolveGuideSurface(route: string): GuideSurface {
+  return route.startsWith("/docs") ? "docs" : "app";
+}
+
+function isGuideSurfaceEnabled(surface: string): boolean {
+  if (!isGuideSurface(surface)) return false;
+  return guideConfig.surfaces?.[surface]?.enabled ?? surface === "app";
+}
+
+function isGuideSurface(surface: string): surface is GuideSurface {
+  return surface === "app" || surface === "docs";
+}

package/templates/react-router/app/guide/actions.ts

@@ -0,0 +1,3 @@
+import type { RaybaseAction } from "@raybase/core/actions";
+
+export const guideActions: RaybaseAction[] = [];

package/templates/react-router/app/guide/config.ts

@@ -0,0 +1,21 @@
+import type { GuideConfig } from "@raybase/guide";
+
+export const guideConfig = {
+  enabled: true,
+  surfaces: {
+    app: { enabled: true, audience: "signed-in" },
+    docs: { enabled: true, audience: "signed-in" }
+  },
+  agent: {
+    name: "guide",
+    title: "Guide"
+  },
+  limits: {
+    publicIpHourlyRequests: 20,
+    publicIpHourlyOutputTokens: 12000,
+    publicDailyRequests: 200,
+    publicDailyOutputTokens: 60000,
+    signedInDailyRequests: 50,
+    maxCorpusSnippets: 8
+  }
+} satisfies GuideConfig;

package/templates/react-router/app/guide/corpus.gen.ts

@@ -0,0 +1,4 @@
+import type { GuideCorpusDocument } from "@raybase/guide";
+import manifest from "./corpus.manifest.json";
+
+export const generatedGuideCorpus = manifest.documents as GuideCorpusDocument[];

package/templates/react-router/app/guide/corpus.manifest.json

@@ -0,0 +1,22 @@
+{
+  "schemaVersion": 1,
+  "generatedAt": "2026-11-14T04:05:33.795Z",
+  "sources": [
+    {
+      "kind": "guide",
+      "path": "content/guide"
+    }
+  ],
+  "documents": [
+    {
+      "id": "faq:capability-map.md",
+      "title": "What Guide can do in this app",
+      "source": "faq",
+      "text": "Guide should answer from the checked in app docs, help knowledge, and explicit Agent actions registered by the app. It can explain what the app tracks, where to go, how common workflows work, what the current user is allowed to do, and which tasks it can help perform. When the app registers Agent actions, Guide may use those actions only after the user clearly asks and the action policy allows it. If no action is registered for a task, it can explain the workflow but should not claim it can perform the task. Guide should not expose raw tool names, internal errors, JSON, SQL, source code details, admin/operator capabilities, secrets, or implementation jargon. If context is missing or a tool fails, it should respond plainly, offer a useful next step, and ask one clarifying question only when needed.",
+      "public": false,
+      "guideContext": "app-capability-map",
+      "updatedAt": "2026-11-14T04:05:26.038Z",
+      "hash": "sha256:9744984def63323f0435b3386509a0ff7d6f6a9986d1f159a1d04d037351ee53"
+    }
+  ]
+}

package/templates/react-router/app/guide/corpus.ts

@@ -0,0 +1,4 @@
+import type { GuideCorpusDocument } from "@raybase/guide";
+import { generatedGuideCorpus } from "./corpus.gen";
+
+export const guideCorpus = generatedGuideCorpus satisfies GuideCorpusDocument[];

package/templates/react-router/app/guide/resources.json

@@ -0,0 +1,4 @@
+{
+  "schemaVersion": 1,
+  "resources": []
+}

package/templates/react-router/content/guide/capability-map.md

@@ -0,0 +1,13 @@
+---
+title: What Guide can do in this app
+guideContext: app-capability-map
+public: false
+---
+
+Guide should answer from the checked-in app docs, help knowledge, and explicit Agent actions registered by the app.
+
+It can explain what the app tracks, where to go, how common workflows work, what the current user is allowed to do, and which tasks it can help perform.
+
+When the app registers Agent actions, Guide may use those actions only after the user clearly asks and the action policy allows it. If no action is registered for a task, it can explain the workflow but should not claim it can perform the task.
+
+Guide should not expose raw tool names, internal errors, JSON, SQL, source-code details, admin/operator capabilities, secrets, or implementation jargon. If context is missing or a tool fails, it should respond plainly, offer a useful next step, and ask one clarifying question only when needed.

package/templates/tanstack-start/content/guide/capability-map.md

@@ -0,0 +1,17 @@
+---
+title: What Guide can do in this app
+guideContext: app-capability-map
+public: false
+---
+
+Guide should answer from the checked-in app docs, help knowledge, and explicit Agent actions registered by the app.
+
+It can explain what the app tracks, where to go, how common workflows work, what the current user is allowed to do, and which tasks it can help perform.
+
+In the Team Tasks starter, Guide can summarize visible projects and tasks, list visible projects and tasks, create projects, create tasks, update task fields, mark tasks done, archive tasks or projects, and list assignable users through narrow declared app actions that share the same policies and invariants as the UI workflow.
+
+Guide should prefer archive over hard delete. It does not have hard-delete actions in its allow-list. If a user asks to permanently delete work, explain that deletion is handled from the app UI by someone with permission after the item is archived.
+
+When the app registers Agent actions, Guide may use those actions only after the user clearly asks and the action policy allows it. If no action is registered for a task, it can explain the workflow but should not claim it can perform the task.
+
+Guide should not expose raw tool names, internal errors, JSON, SQL, source-code details, admin/operator capabilities, or implementation jargon. If context is missing or a tool fails, it should respond plainly, offer a useful next step, and ask one clarifying question only when needed.

package/templates/tanstack-start/src/components/guide-widget.tsx

@@ -0,0 +1,41 @@
+import { useRouter } from "@tanstack/react-router";
+import { RaybaseAgentWidget } from "@raybase/agent-ui";
+import { useEffect } from "react";
+import { guideConfig } from "../guide/config";
+
+export function GuideWidget() {
+  const router = useRouter();
+
+  useEffect(() => {
+    const refreshData = () => {
+      void router.invalidate();
+    };
+    window.addEventListener("raybase:data-changed", refreshData);
+    return () => window.removeEventListener("raybase:data-changed", refreshData);
+  }, [router]);
+
+  return (
+    <RaybaseAgentWidget
+      agentName={guideConfig.agent?.name ?? "guide"}
+      enabled={guideConfig.enabled ?? true}
+      isSurfaceEnabled={isGuideSurfaceEnabled}
+      resolveSurface={resolveGuideSurface}
+      title={guideConfig.agent?.title ?? "Guide"}
+    />
+  );
+}
+
+type GuideSurface = "app" | "docs";
+
+function resolveGuideSurface(route: string): GuideSurface {
+  return route.startsWith("/docs") ? "docs" : "app";
+}
+
+function isGuideSurfaceEnabled(surface: string): boolean {
+  if (!isGuideSurface(surface)) return false;
+  return guideConfig.surfaces?.[surface]?.enabled ?? surface === "app";
+}
+
+function isGuideSurface(surface: string): surface is GuideSurface {
+  return surface === "app" || surface === "docs";
+}

package/templates/tanstack-start/src/guide/actions.ts

@@ -0,0 +1,17 @@
+import type { RaybaseAction } from "@raybase/core/actions";
+import type { RaybaseEnv } from "@raybase/core/worker";
+import { actions } from "../actions";
+
+// Keep Guide on a narrow allow-list of app-declared actions.
+export const guideActions = [
+  actions.workspaceSnapshot,
+  actions.listVisibleProjects,
+  actions.listVisibleTodos,
+  actions.createProject,
+  actions.createTodo,
+  actions.updateTodo,
+  actions.markTodoDone,
+  actions.archiveTodo,
+  actions.archiveProject,
+  actions.listAssignableUsers
+] satisfies Array<RaybaseAction<any, any, RaybaseEnv>>;

package/templates/tanstack-start/src/guide/config.ts

@@ -0,0 +1,21 @@
+import type { GuideConfig } from "@raybase/guide";
+
+export const guideConfig = {
+  enabled: true,
+  surfaces: {
+    app: { enabled: true, audience: "signed-in" },
+    docs: { enabled: true, audience: "signed-in" }
+  },
+  agent: {
+    name: "guide",
+    title: "Guide"
+  },
+  limits: {
+    publicIpHourlyRequests: 20,
+    publicIpHourlyOutputTokens: 12000,
+    publicDailyRequests: 200,
+    publicDailyOutputTokens: 60000,
+    signedInDailyRequests: 50,
+    maxCorpusSnippets: 8
+  }
+} satisfies GuideConfig;

package/templates/tanstack-start/src/guide/corpus.gen.ts

@@ -0,0 +1,4 @@
+import type { GuideCorpusDocument } from "@raybase/guide";
+import manifest from "./corpus.manifest.json";
+
+export const generatedGuideCorpus = manifest.documents as GuideCorpusDocument[];