Host knowledge writing

Version: 1.3

Readers: people who write or review agent knowledge documents when a Cadau assistant is embedded on a host page (your business-system page) — usually product / domain experts working with frontend or integration developers.

Voice: body copy prefers natural language a user can understand; API paths, field names, and env vars belong in dedicated sections or parentheses. Do not replace descriptions of user behavior with implementation nouns (same convention as Product specification in the repo).

Related: Website integration (§5 in-reply navigation), Embed contract.

---

1. What a “host knowledge document” is

Host means your business system that mounts the Cadau embed widget (or an equivalent SDK), not the Cadau console itself.

Host knowledge documents are Markdown notes you write and mount under My agents → knowledge documents (or workspace-layer knowledge; see §2), so that agent can retrieve and answer in your page context. The goals are:

• Make the assistant talk about your product correctly (what pages are called, what users can do, common limits);
• Make the assistant guide people to the right page (via §6 navigation links, executed by the host-page whitelist);
• Make the assistant not invent data, permissions, or APIs you have not opened.

Built-in Cadau main-site help assistant knowledge (for example module.workspace) does not automatically apply on the host page. Embed scenes must follow this document + your docs + the action table the host page actually implements.

---

2. Which layer to write (Cadau’s three knowledge layers)

Product knowledge has global / workspace / user layers (Product specification §3.2.1). On the host side, prefer:

For website embed integration, at least maintain agent-owned knowledge for that embed agent. If several assistants in the same workspace share one business voice, also keep workspace-layer documents so copies do not drift.

Index shape: when there are many documents, prefer one overview + theme folders (each folder may have index.json; see AI rebuild knowledge index rules). Example: examples/hr-multi-tenant/docs/宿主知识文档/导读.md (two levels: root guide + theme subfolders).

---

3. Writing principles (required)

3.1 User language first

• Write first: who, on which page, can finish what result (for example “On the org chart page, right-click a department to add a child department”).
• Write second: matching HTTP method, path, JSON fields (for the assistant to debug and cite; not as first-screen talk).
• Button, menu, and error names must match host-page UI copy, so the assistant does not say “click Workspace” when the page says “workspace”.

3.2 Truth bounds

• Write only capabilities the host page already implements; mark unreleased work as “planned” or do not write it, so the assistant does not promise the impossible.
• If business data is not stored in Cadau (legacy-host enhancement; see Product specification §4.2.4 and Host agent run and data scope in this directory), the assistant must not invent order numbers, customer balances, or other tenants’ data. Guide the user to look on the page in the current signed-in context, or call APIs you have opened and documented.
• Tenant / org / workspace isolation: write clearly “the assistant must stay within what the current user can see” and “do not invent other tenants’ ids”. In embed, history / live support / tickets are isolated by the widget to the current signed-in user (or website visitor). Do not write in knowledge that “everyone shares one chat history”.

3.3 Stay aligned with host-page code

• Action names and param names in in-reply navigation (§6) must match exactly (case-sensitive) the host-page action whitelist (for example executeHostAction / handleMindlinkWidgetAction).
• After code adds or removes actions, update the action registry table in knowledge (§6.4) in the same release.
• When host implementation changes (route hash, module name), update example links in knowledge at the same time.
• If the host leaves entry.auto_execute_navigation on (widget default on): when the user says “open … for me”, the widget automatically runs the first navigation link in the reply — knowledge must keep the first link as the most relevant page, and every action in the table must be implemented (see 网站集成说明.md §5.6).

3.4 Security and compliance

• Do not put in knowledge documents: embed access tokens, API keys, passwords, private keys, or complete personal-data samples.
• Do not teach the assistant to output unsafe link protocols such as javascript: or data:; outbound links only http/https, and domains should be on the host-page open_url allowlist.
• For high-risk operations such as deleting data, changing permissions, or transferring money: knowledge must say “the user must confirm on the host page”. Do not assume the assistant can execute them directly (unless the host has implemented a gated, authenticated action and you have written the flow).

3.5 Length and retrievability

• Prefer one theme per .md (for example “org chart page”, “order list filters”); split long pieces and create top-level theme folders.
• After edits, run “Regenerate index with AI” on that agent in Cadau (see AI rebuild knowledge index rules), or conversation may still pick documents from the old index.

---

4. Recommended document structure (template)

Organize as one overview + several topic pieces; topic names should match host-page modules.

# <business system name> · <assistant role> knowledge

> Purpose: retrieval for the Cadau agent embedded on <host page name>.
> Scope: only <system/module>; not a substitute for Cadau product spec.
> Maintenance: keep in sync with host page version <x.y>; code action table in §5.

## 1. What users can do on the page (user language)

- (Capabilities, limits, and relations to other pages, by page or role)

## 2. How the browser talks to the backend (summary for the assistant)

- Same-origin / proxy convention, how auth works (in user language: “after sign-in the server issues an embed session”)
- How tenant/workspace is obtained (write “trust the API response; do not invent”)
- What the user sees on error

## 3. Business APIs or data conventions (optional; put implementation detail here)

- Base URL, path table, required fields, common error codes

## 4. Special notes for the embed assistant on this site

- Widget shape (bottom-right / inline), whether it is site-wide
- Differences from Cadau main-site capability (for example it cannot click host buttons for the user)
- When the user clearly asks to open a page, the widget may auto-run the first navigation link (output links in the right order)

## 5. In-reply navigation (mindlink://action/)

- Action registry table (§6.4)
- Reply rules: when to put 1–3 links at the end; for auto-navigation the first must be the most relevant
- Example Markdown links (match the registry)

## 6. Version and maintenance

- Matching host repo path, owner, last updated

In-repo example: examples/hr-multi-tenant/docs/宿主知识文档/导读.md (HR multi-tenant · full Chinese split docs; overview in the same folder 00-总则与功能导航.md).

---

5. Suggested mount list (minimum for embed integration)

For website embed, that agent should at least mount:

Do not put embed access tokens in knowledge documents. Tokens belong in host-page config, env vars, or backend embed-session / mint logic.

---

6. In-reply navigation chapter (required for embed)

6.1 Mechanism (for writers)

1. Agree in knowledge: when you need to open a page / view with filters for the user, the assistant uses a Markdown link plus protocol mindlink://action/.
2. After a click, the Cadau widget emits an action event to the host page (emit_event, kind: mindlink_action).
3. The host page only runs registered actions; unregistered actions should get a friendly message and not run arbitrary scripts.

Syntax:

`link label`

• Action name: prefer page.<module> or module.<module>, matching the host-page whitelist key.
• Query params: standard URL query string (for example status, id, tenant_id); optional label for copy or analytics; the host page may ignore it.
• Link label: words a user understands (for example “Open pending orders”), not the action name.

Full examples: Website integration §5.

6.2 Reply rules (put in knowledge so the model follows them)

• When the user asks “where do I look / open this for me / jump”: put 1–3 registered action links at the end of the body, with params matching current conversation context (for example the order id just mentioned).
• When the user clearly asks to open (for example “open the org chart for me”) and the host has not turned auto-navigation off: the widget automatically runs the first link after the reply — the first must be the most relevant, implemented action; remaining links are for manual clicks.
• Do not dump a dozen links at once; do not give an action that is not in the table.
• Do not use Cadau main-site-only actions (for example module.workspace, chat.new-session) unless the host page has mapped them; otherwise clicks do nothing (see Help action links).
• For filter params not implemented yet (for example tab=tree but the host only jumps to the page): note in the action table “param reserved; currently only opens the page”, so the assistant does not promise an unimplemented subview.

6.3 The host page must implement (engineering; finish before writing knowledge)

• Handle mindlink_action in widget.on("action", …) (and optionally open_url, open_module).
• Maintain HOST_ACTIONS or an equivalent route table; unknown actions say “not supported yet”.
• Production: backend mints short-lived tokens and issues embed-session; browser init app_id and user_agent_id match the registration; on expiry, updateAuth.

Implementation: Website integration §4, §4.3, §5.3; HR example: examples/hr-multi-tenant/web/src/mindlinkHostActions.ts.

6.4 Action registry table (copy into each host knowledge document §5)

Requirement: the host product team and frontend maintain this table together, row-by-row identical to the code whitelist.

Example links (must match the table row by row):

- `Open pending orders`
- `View org chart`

If a param is not implemented on the host yet (for example tab=tree), note in the table “param reserved; currently only opens the page”, so the assistant does not promise an unimplemented subview.

---

7. Quality checklist (before publish)

• [ ] Page/button names match host-page UI, and nothing describes a retired feature.
• [ ] No tokens, secrets, or real user privacy samples.
• [ ] Action registry matches host-page whitelist code; example links are clickable and jump correctly.
• [ ] Tenant/permission bounds are stated, including “do not invent ids”.
• [ ] After document changes, “Regenerate index with AI” was run for that agent.
• [ ] Integration on a real host page: can converse, can click navigation links in replies; when the user says “open xx for me”, auto-navigation matches expectations (see Website integration §5.6, §6).

---

8. Suggested maintenance flow

1. Requirement change (new page, route change) → update host-page whitelist code → update knowledge §5 action table and §1 user-capability notes.
2. API change → update §3 API summary, and spot-check that the assistant is not still citing old paths.
3. Release → regenerate the index with AI → on a staging host page, regress 3–5 typical questions (including “open xx page for me” and “where do I look”).
4. Multiple environments (dev/staging/production) → if actions or copy differ, use different workspaces or different agents for knowledge; do not mix production truth.

---

9. Further reading

---

10. Document revisions