@vertesia/appgen-docs 1.5.0-dev.20260806.125520Z → 1.5.0-dev.20260826.064249Z

package/lib/docs/interaction-runtime.md

@@ -0,0 +1,47 @@
+# Installed Capability Runtime Execution
+
+Use the root `VertesiaClient` for app-owned interaction execution. For an immutable candidate, call `client.withAppVersion(versionId)` once before any Studio or Store request.
+
+## Interactions
+
+`executeByName` accepts the portable app interaction ref and an `InteractionExecutionPayload`. Put prompt inputs under `data`; the returned result is already enhanced with typed accessors.
+
+```ts
+interface StatusBriefingInput {
+  project_id: string;
+  tasks: Array<{ id: string; title: string; status: string }>;
+}
+
+interface StatusBriefingResult {
+  summary: string;
+  evidence: Array<{ id: string; title: string; status: string }>;
+}
+
+const execution = await client.interactions.executeByName<StatusBriefingResult, StatusBriefingInput>(
+  `app:${APP_NAME}:main:project-status-briefing`,
+  { data: input },
+);
+const briefing = execution.result.object();
+```
+
+Use `execution.result.text()` for text output and `execution.result.objects()` for multiple JSON results. Validate the parsed object against the exact durable input snapshot before displaying or persisting it. Do not reimplement `/api/v1/execute` with raw `fetch`.
+
+## Processes and activities
+
+Installed app activities are internal process nodes. The root SDK has no `client.activities` execution API, so exercise an activity through a packaged process that references it. Start processes through the Store agent API; `client.processes` manages definitions and has no `executeByName` method.
+
+```ts
+const run = await client.agents.start({
+  process_id: `app:${APP_NAME}:milestone-transition`,
+  run_type: 'programmatic',
+  data: { milestone_id, target_status: 'complete' },
+});
+await client.agents.streamMessages(run.id);
+const terminal = await client.agents.retrieveProcess(run.id);
+const { context } = await client.agents.getContext(run.id);
+if (terminal.status !== 'completed') {
+  throw new Error(String(context.error ?? terminal.status));
+}
+```
+
+A package summary containing an activity proves registration only, not runtime execution. Unit-test the exact interaction and process call shapes with focused SDK mocks before constructing an immutable candidate. Never invent `client.activities.executeByName` or `client.processes.executeByName`.

package/lib/docs/package-types.md

@@ -20,6 +20,7 @@ When creating or searching Store objects, pass the app type code string:
 
 ```ts
 await client.objects.create({
+  name: 'Supplier review',
   type: CASE_TYPE,
   properties: {
     title: 'Supplier review',

package/lib/docs/store-objects.md

@@ -4,6 +4,8 @@ Use the Vertesia client from `useUserSession()` in browser code and the injected
 
 App-owned types are referenced by their **in-code string** `app:<app-name>:<local>`, never a resolved ObjectId — pass the string straight to `search`/`create` and derive it from a single `APP_NAME` constant (= package.json name = VITE_APP_NAME = manifest name) so the app stays portable. See `package-types.md` for the rule.
 
+Every `objects.create` payload requires a top-level `name`. A title inside `properties` does not satisfy this Store contract. Use a stable human-readable value, normally the record title, and keep it in sync when the product renames the record.
+
 ## Search
 
 ```ts
@@ -63,6 +65,7 @@ async function seedCase(client: VertesiaClient, record: { external_id: string; t
   }
 
   return client.objects.create({
+    name: record.title,
     type: CASE_TYPE,
     properties: { ...record, seed_marker: SEED_MARKER },
   });
@@ -75,6 +78,7 @@ For document, review, and intake apps, attach realistic source content to repres
 
 ```ts
 await client.objects.create({
+  name: 'Screening evidence',
   type: `app:${APP_NAME}:evidence`,
   properties: {
     title: 'Screening evidence',

package/lib/docs/tool-server-resource.md

@@ -418,6 +418,11 @@ Registered hooks are exposed as authenticated POST endpoints at `/api/hooks/inst
 app package advertises their endpoint paths under `hooks` for inspection. Studio invokes the conventional endpoints
 directly and treats a 404 as an absent optional hook.
 
+Building an immutable version advertises these definitions but does not execute them. Studio runs the promoted
+version's install hook during promotion reconciliation and runs the previous promoted version's uninstall hook when
+it is replaced or removed. For an unpromoted candidate, validate source registration and package output only; do not
+invoke lifecycle endpoints manually or fail candidate QA because their side effects are absent.
+
 In an appgen capability manifest, declare lifecycle hooks with type `hook` and ids such as
 `app:<app-name>:install` and `app:<app-name>:uninstall`.
 
@@ -476,7 +481,8 @@ Represent it in an appgen capability manifest as a `hook` artifact such as
 ## Application event subscriptions
 
 Subscriptions are declarative package contributions that route matching platform events to an event hook in the same
-app. They do not contain a deployment URL or project scope. Studio derives both when it installs the app.
+app. They do not contain a deployment URL or project scope. Studio derives both from the version selected during
+promotion.
 
 ```typescript
 // src/modules/app/resources/subscriptions/index.ts
@@ -505,6 +511,11 @@ the same event hook with different filters. Inspect the result with `GET /api/pa
 Represent each definition in an appgen capability manifest as a `subscription` artifact such as
 `app:<app-name>:content-updated`.
 
+An unpromoted candidate exposes these package definitions but does not create protected Event Bus subscriptions, and
+matching events are not delivered to that candidate's hook. Candidate validation is therefore limited to source and
+package-summary wiring. Use Event Bus subscription and delivery evidence only after the version has been explicitly
+promoted.
+
 ---
 
 ## Collection registration & icons

package/lib/docs/ui-interfaces.d.ts

@@ -55,6 +55,7 @@ export * from './LanguageSwitcher';
 export * from './label';
 export * from './MessageBox';
 export * from './modal';
+export * from './overflowTabs';
 export * from './Panel';
 export * from './popover';
 export * from './radioGroup';
@@ -1010,13 +1011,20 @@ interface GenericPageNavHeaderProps {
     children?: ReactNode;
     className?: string;
     useDynamicBreadcrumbs?: boolean;
+    /**
+     * Parent page linked from the breadcrumbs when there is no history chain to walk (the user
+     * landed on this URL directly). Give it as an absolute app path, including the module mount.
+     */
+    parentPath?: string;
+    /** Label for {@link parentPath}; defaults to its last segment, title-cased. */
+    parentLabel?: string;
 }
 interface BreadcrumbElementProps {
     href?: string;
     clearBreadcrumbs?: boolean;
     children?: ReactNode;
 }
-export declare function GenericPageNavHeader({ className, children, title, description, actions, breadcrumbs, useDynamicBreadcrumbs, }: GenericPageNavHeaderProps): JSX.Element;
+export declare function GenericPageNavHeader({ className, children, title, description, actions, breadcrumbs, useDynamicBreadcrumbs, parentPath, parentLabel, }: GenericPageNavHeaderProps): JSX.Element;
 export {};
 
 // -----------------------------------------------------------------------------
@@ -1068,6 +1076,12 @@ export interface ModernAgentConversationProps {
     onShowDetails?: () => void;
     /** Whether workflow control actions such as cancel should be shown. */
     allowWorkflowControl?: boolean;
+    /**
+     * Workstream selected on mount instead of "all" — use it to open the conversation on one
+     * sub-agent (a process agent node's workstream is its node id). Initial value only; the user's
+     * later tab choices win.
+     */
+    initialWorkstream?: string;
     /** Called when files are dropped/pasted/selected */
     onFilesSelected?: (files: File[]) => void;
     /** Currently uploaded files to display */