Skip to content

The open-source agent harness - the runtime layer that turns an LLM into a working agent.

added base docs for UI SDK (#103)

sajal-truefoundryde3000c064a0
diff --git a/docs/docs.json b/docs/docs.json
index 5d5cf7e82..49b60a3af 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -4,9 +4,14 @@
"name": "TrueForge",
"logo": {
"light": "/logo/light.svg",
- "dark": "/logo/dark.svg"
+ "dark": "/logo/dark.svg",
+ "href": "https://trueforge.dev"
},
- "favicon": "/favicon.png",
+ "favicon": {
+ "light": "/logo/favicon-light.svg",
+ "dark": "/logo/favicon-dark.svg"
+ },
+ "description": "Open-source agent harness — MCP tools, skills, sandboxing, approvals, and subagents.",
"colors": {
"primary": "#0D9488",
"light": "#14B8A6",
@@ -18,38 +23,103 @@
"url": "https://example.com"
}
],
+ "appearance": {
+ "default": "system"
+ },
"navigation": {
- "groups": [
- {
- "group": "Getting Started",
- "pages": ["introduction", "quickstart"]
- },
+ "tabs": [
{
- "group": "Capabilities",
- "pages": [
- "models",
- "mcp-servers",
- "skills",
- "sandbox",
+ "tab": "Documentation",
+ "groups": [
{
- "group": "Context Engineering",
+ "group": "Getting Started",
+ "pages": ["introduction", "quickstart"]
+ },
+ {
+ "group": "Capabilities",
"pages": [
- "context-engineering/overview",
- "context-engineering/subagents",
- "context-engineering/deferred-tool-loading",
- "context-engineering/code-mode",
- "context-engineering/large-tool-responses"
+ "models",
+ "mcp-servers",
+ "skills",
+ "sandbox",
+ {
+ "group": "Context Engineering",
+ "pages": [
+ "context-engineering/overview",
+ "context-engineering/subagents",
+ "context-engineering/deferred-tool-loading",
+ "context-engineering/code-mode",
+ "context-engineering/large-tool-responses"
+ ]
+ },
+ "human-in-the-loop",
+ "ask-user-questions",
+ "generative-ui"
]
},
- "human-in-the-loop",
- "ask-user-questions",
- "generative-ui"
+ {
+ "group": "API",
+ "pages": ["api/overview", "api/agent-spec", "api/turn-events"]
+ }
]
},
{
- "group": "API",
- "pages": ["api/overview", "api/agent-spec", "api/turn-events"]
+ "tab": "UI SDK",
+ "groups": [
+ {
+ "group": "Get started",
+ "pages": ["ui-sdk/index", "ui-sdk/get-started/installation", "ui-sdk/get-started/quickstart"]
+ },
+ {
+ "group": "Concepts",
+ "pages": ["ui-sdk/concepts/architecture", "ui-sdk/concepts/agent-modes", "ui-sdk/concepts/server-contract"]
+ },
+ {
+ "group": "Guides",
+ "pages": [
+ "ui-sdk/guides/layouts",
+ "ui-sdk/guides/theming",
+ "ui-sdk/guides/slot-overrides",
+ "ui-sdk/guides/custom-server",
+ "ui-sdk/guides/mcp-oauth",
+ "ui-sdk/guides/troubleshooting"
+ ]
+ },
+ {
+ "group": "API reference",
+ "pages": [
+ "ui-sdk/reference/trueforge-ui",
+ "ui-sdk/reference/theme",
+ "ui-sdk/reference/containers",
+ "ui-sdk/reference/atoms",
+ "ui-sdk/reference/hooks",
+ "ui-sdk/reference/server",
+ "ui-sdk/reference/events",
+ "ui-sdk/reference/catalog"
+ ]
+ }
+ ]
}
]
+ },
+ "navbar": {
+ "links": [
+ {
+ "type": "github",
+ "href": "https://github.com/truefoundry/trueforge"
+ }
+ ],
+ "primary": {
+ "type": "button",
+ "label": "TrueFoundry",
+ "href": "https://www.truefoundry.com"
+ }
+ },
+ "footer": {
+ "socials": {
+ "github": "https://github.com/truefoundry",
+ "x": "https://x.com/truefoundry",
+ "linkedin": "https://in.linkedin.com/company/truefoundry"
+ }
}
}
diff --git a/docs/logo/dark.svg b/docs/logo/dark.svg
new file mode 100644
index 000000000..a46d05feb
--- /dev/null
+++ b/docs/logo/dark.svg
@@ -0,0 +1,13 @@
+<svg width="737" height="120" viewBox="0 0 737 120" fill="none" xmlns="http://www.w3.org/2000/svg">
+<g clip-path="url(#clip0_10580_645)">
+<path d="M0 0.015625L40 20.0156V40L20 40V80.0156H40V100.016L0 120.016V0.015625Z" fill="white"/>
+<path d="M120 0L80 20V40H100V80H80V100L120 120V0Z" fill="white"/>
+<path d="M59.9971 39.8193C61.0556 45.6178 63.1951 50.1614 66.5771 53.5215C69.9455 56.868 74.4738 58.9678 80.2051 60.0088C74.4712 61.0714 69.9429 63.2075 66.5752 66.5752C63.1954 69.955 61.0558 74.5036 59.9971 80.2666C58.933 74.5031 56.7854 69.9547 53.4004 66.5752C50.0276 63.2078 45.4981 61.0704 39.7725 60.0078C45.4953 58.9668 50.0251 56.8676 53.3984 53.5215C56.7857 50.1616 58.9332 45.6182 59.9971 39.8193Z" fill="white" stroke="white" stroke-width="1.6" stroke-linejoin="round"/>
+</g>
+<path d="M622.099 24.752C631.17 24.752 637.822 27.7322 642.056 33.6934V27.084H659.938V90.4531C659.938 99.87 656.785 107.127 650.479 112.225C644.172 117.408 636.008 120 625.986 120C614.669 120 603.784 116.76 593.33 110.28L602.66 96.1553C611.559 101.252 619.248 103.801 625.728 103.801C635.835 103.801 640.89 98.7473 640.89 88.6396V84.752C636.57 89.8491 630.306 92.3975 622.099 92.3975C613.632 92.3974 606.548 89.2442 600.846 82.9375C595.23 76.6308 592.423 68.5094 592.423 58.5742C592.423 48.6393 595.23 40.5185 600.846 34.2119C606.548 27.9052 613.632 24.752 622.099 24.752ZM292.13 69.46C292.13 76.285 295.456 79.6982 302.108 79.6982C310.229 79.6982 314.29 75.421 314.29 66.8682V27.084H333.729V94.4707H315.975V87.3438C311.914 93.564 305.391 96.6738 296.406 96.6738C288.458 96.6738 282.497 94.773 278.522 90.9717C274.635 87.1704 272.691 81.7275 272.691 74.6436V27.084H292.13V69.46ZM378.339 24.752C388.62 24.752 396.525 27.7322 402.054 33.6934C407.669 39.6545 410.478 48.0349 410.478 58.834C410.478 61.2528 410.391 63.758 410.218 66.3496H362.658C364.732 75.5937 370.693 80.2158 380.542 80.2158C384.084 80.2158 387.237 79.6109 390.002 78.4014C392.766 77.1055 396.049 74.8595 399.851 71.6631L410.478 83.8447C401.579 92.3976 391.427 96.6738 380.023 96.6738C368.965 96.6738 360.153 93.4345 353.587 86.9551C347.108 80.4757 343.868 71.836 343.868 61.0371C343.868 50.4108 346.978 41.7279 353.198 34.9893C359.419 28.1642 367.799 24.752 378.339 24.752ZM499.098 24.752C509.465 24.752 517.974 28.121 524.626 34.8594C531.278 41.5116 534.604 50.1077 534.604 60.6475C534.604 71.2738 531.278 79.9566 524.626 86.6953C517.974 93.3474 509.465 96.6738 499.098 96.6738C488.644 96.6738 480.091 93.3476 473.438 86.6953C466.786 79.9567 463.46 71.2738 463.46 60.6475C463.46 50.1077 466.786 41.5116 473.438 34.8594C480.091 28.1207 488.644 24.752 499.098 24.752ZM704.464 24.752C714.745 24.752 722.65 27.7322 728.179 33.6934C733.794 39.6545 736.603 48.0349 736.603 58.834C736.603 61.2528 736.516 63.758 736.343 66.3496H688.783C690.857 75.5937 696.818 80.2158 706.667 80.2158C710.209 80.2158 713.362 79.6109 716.127 78.4014C718.891 77.1055 722.174 74.8595 725.976 71.6631L736.603 83.8447C727.704 92.3976 717.552 96.6738 706.148 96.6738C695.09 96.6738 686.278 93.4345 679.712 86.9551C673.233 80.4757 669.993 71.836 669.993 61.0371C669.993 50.4108 673.103 41.7279 679.323 34.9893C685.544 28.1642 693.924 24.752 704.464 24.752ZM194.087 27.085H209.249V41.5996H194.087V73.0898C194.087 75.3359 194.605 76.9345 195.642 77.8848C196.678 78.7486 198.277 79.1797 200.437 79.1797C202.078 79.1797 204.626 78.8347 208.082 78.1436L210.285 93.6943C204.842 95.3358 199.702 96.1562 194.864 96.1562C187.694 96.1562 182.51 94.6013 179.313 91.4912C176.203 88.3811 174.649 83.4137 174.648 76.5889V41.5996H162.855V27.085H174.648V7.3877H194.087V27.085ZM254.532 25.9189C257.21 25.9189 260.883 26.6959 265.548 28.251L261.919 45.3574C257.858 44.4071 254.921 43.9316 253.106 43.9316C248.787 43.9317 245.374 45.6162 242.869 48.9854C240.364 52.2683 239.111 56.8044 239.111 62.5928V94.4717H219.673V27.085H237.686V36.6748C241.314 29.5042 246.93 25.919 254.532 25.9189ZM579.519 25.9189C582.197 25.9189 585.869 26.6959 590.534 28.251L586.905 45.3574C582.845 44.4072 579.908 43.9317 578.094 43.9316C573.774 43.9316 570.361 45.616 567.855 48.9854C565.35 52.2683 564.098 56.8044 564.098 62.5928V94.4717H544.659V27.085H562.672V36.6748C566.3 29.5043 571.916 25.9191 579.519 25.9189ZM449.276 0C453.942 0 458.866 0.77795 464.05 2.33301L460.681 16.7168C458.175 16.1121 455.627 15.8096 453.035 15.8096C450.53 15.8096 448.758 16.3712 447.722 17.4941C446.685 18.5309 446.167 20.3892 446.167 23.0674V27.084H460.292V41.5986H446.167V94.4707H426.729V41.5986H415.454V27.084H426.729V22.2891C426.729 7.42983 434.244 0.000142379 449.276 0ZM499.098 41.209C494.346 41.209 490.501 42.9803 487.563 46.5225C484.626 50.0645 483.158 54.773 483.158 60.6475C483.158 66.6084 484.626 71.3603 487.563 74.9023C490.501 78.4445 494.346 80.2158 499.098 80.2158C503.849 80.2157 507.65 78.4444 510.501 74.9023C513.438 71.3602 514.907 66.6085 514.907 60.6475C514.907 54.7729 513.438 50.0645 510.501 46.5225C507.564 42.9806 503.763 41.2091 499.098 41.209ZM626.764 41.3389C622.358 41.3389 618.772 42.9373 616.008 46.1338C613.33 49.2439 611.99 53.3908 611.99 58.5742C611.99 63.7578 613.373 67.948 616.138 71.1445C618.902 74.341 622.444 75.9394 626.764 75.9395C631.17 75.9395 634.755 74.341 637.52 71.1445C640.284 67.948 641.667 63.7578 641.667 58.5742C641.667 53.3907 640.284 49.2439 637.52 46.1338C634.755 42.9374 631.17 41.3389 626.764 41.3389ZM378.08 39.9131C370.218 39.9131 365.207 44.1902 363.047 52.7432H391.945C390.995 44.1904 386.374 39.9132 378.08 39.9131ZM704.205 39.9131C696.343 39.9131 691.332 44.1902 689.172 52.7432H718.07C717.12 44.1904 712.499 39.9132 704.205 39.9131Z" fill="white"/>
+<defs>
+<clipPath id="clip0_10580_645">
+<rect width="120" height="120" fill="white"/>
+</clipPath>
+</defs>
+</svg>
diff --git a/docs/logo/favicon-dark.svg b/docs/logo/favicon-dark.svg
new file mode 100644
index 000000000..3718b58ad
--- /dev/null
+++ b/docs/logo/favicon-dark.svg
@@ -0,0 +1,12 @@
+<svg width="120" height="120" viewBox="0 0 120 120" fill="none" xmlns="http://www.w3.org/2000/svg">
+<g clip-path="url(#clip0_10581_4008)">
+<path d="M-0.000793457 0.015625L39.9992 20.0156V40L19.9992 40V80.0156H39.9992V100.016L-0.000793457 120.016V0.015625Z" fill="white"/>
+<path d="M119.999 0L79.9992 20V40H99.9992V80H79.9992V100L119.999 120V0Z" fill="white"/>
+<path d="M59.9955 39.8193C61.054 45.6178 63.1935 50.1614 66.5756 53.5215C69.9439 56.868 74.4722 58.9678 80.2035 60.0088C74.4696 61.0714 69.9413 63.2075 66.5736 66.5752C63.1938 69.955 61.0542 74.5036 59.9955 80.2666C58.9314 74.5031 56.7838 69.9547 53.3988 66.5752C50.026 63.2078 45.4965 61.0704 39.7709 60.0078C45.4938 58.9668 50.0235 56.8676 53.3969 53.5215C56.7841 50.1616 58.9316 45.6182 59.9955 39.8193Z" fill="white" stroke="white" stroke-width="1.6" stroke-linejoin="round"/>
+</g>
+<defs>
+<clipPath id="clip0_10581_4008">
+<rect width="120" height="120" fill="white"/>
+</clipPath>
+</defs>
+</svg>
diff --git a/docs/logo/favicon-light.svg b/docs/logo/favicon-light.svg
new file mode 100644
index 000000000..7e28ee9a0
--- /dev/null
+++ b/docs/logo/favicon-light.svg
@@ -0,0 +1,12 @@
+<svg width="140" height="140" viewBox="0 0 140 140" fill="none" xmlns="http://www.w3.org/2000/svg">
+<g clip-path="url(#clip0_10581_1729)">
+<path d="M-0.000976562 0.0195312L46.6657 23.3529V46.668L23.3324 46.668V93.3529H46.6657V116.686L-0.000976562 140.02V0.0195312Z" fill="#05090E"/>
+<path d="M139.999 0L93.3324 23.3333V46.6667H116.666V93.3333H93.3324V116.667L139.999 140V0Z" fill="#05090E"/>
+<path d="M69.9941 46.4561C71.2291 53.2208 73.7252 58.5213 77.6709 62.4414C81.6 66.345 86.8814 68.7951 93.5664 70.0098C86.8784 71.2497 81.5974 73.7435 77.6689 77.6719C73.7259 81.615 71.2293 86.921 69.9941 93.6445C68.7527 86.9203 66.2461 81.6138 62.2969 77.6709C58.3624 73.7429 53.0791 71.2496 46.4004 70.0098C53.076 68.7952 58.3597 66.3456 62.2949 62.4424C66.2468 58.5225 68.7529 53.2215 69.9941 46.4561Z" fill="#6D58FB" stroke="#6D58FB" stroke-width="1.86667" stroke-linejoin="round"/>
+</g>
+<defs>
+<clipPath id="clip0_10581_1729">
+<rect width="140" height="140" fill="white"/>
+</clipPath>
+</defs>
+</svg>
diff --git a/docs/logo/light.svg b/docs/logo/light.svg
new file mode 100644
index 000000000..08d5127d7
--- /dev/null
+++ b/docs/logo/light.svg
@@ -0,0 +1,13 @@
+<svg width="614" height="100" viewBox="0 0 614 100" fill="none" xmlns="http://www.w3.org/2000/svg">
+<g clip-path="url(#clip0_10581_1412)">
+<path d="M-0.00195312 0.0136719L33.3314 16.6803V33.334L16.6647 33.334V66.6803H33.3314V83.347L-0.00195312 100.014V0.0136719Z" fill="#05090E"/>
+<path d="M99.998 0L66.6647 16.6667V33.3333H83.3314V66.6667H66.6647V83.3333L99.998 100V0Z" fill="#05090E"/>
+<path d="M49.9961 33.1826C50.8782 38.0147 52.6612 41.8005 55.4795 44.6006C58.2863 47.3892 62.0592 49.1393 66.835 50.0068C62.057 50.8924 58.2839 52.6732 55.4775 55.4795C52.6611 58.2959 50.8784 62.0863 49.9961 66.8887C49.1093 62.0858 47.3189 58.2958 44.498 55.4795C41.6875 52.6735 37.9135 50.8924 33.1426 50.0068C37.9113 49.1393 41.6861 47.3898 44.4971 44.6016C47.3198 41.8016 49.1095 38.0151 49.9961 33.1826Z" fill="#6D58FB" stroke="#6D58FB" stroke-width="1.33333" stroke-linejoin="round"/>
+</g>
+<path d="M518.559 20.627C526.12 20.627 531.665 23.1106 535.193 28.0781V22.5703H550.1V75.3789C550.1 83.2261 547.47 89.2739 542.214 93.5215C536.957 97.8409 530.153 100.001 521.8 100.001C512.367 100.001 503.293 97.3008 494.58 91.9014L502.356 80.1299C509.773 84.3774 516.182 86.5019 521.583 86.502C530.008 86.502 534.221 82.2902 534.221 73.8672V70.627C530.62 74.8745 525.399 76.998 518.559 76.998C511.502 76.998 505.597 74.3706 500.845 69.1152C496.164 63.8597 493.823 57.0918 493.823 48.8125C493.823 40.5333 496.164 33.7663 500.845 28.5107C505.597 23.2553 511.502 20.627 518.559 20.627ZM315.383 20.627C323.952 20.627 330.541 23.1106 335.149 28.0781C339.83 33.0457 342.17 40.0293 342.17 49.0283C342.17 51.0441 342.098 53.1322 341.954 55.292H302.312C304.041 62.9954 309.01 66.8477 317.219 66.8477C320.171 66.8476 322.799 66.3429 325.104 65.335C327.408 64.2551 330.144 62.3835 333.312 59.7197L342.17 69.8711C334.753 76.9984 326.292 80.5624 316.787 80.5625C307.57 80.5625 300.225 77.8624 294.752 72.4629C289.351 67.0633 286.65 59.8635 286.65 50.8643C286.65 42.0091 289.243 34.7737 294.428 29.1582C299.612 23.4707 306.598 20.627 315.383 20.627ZM416.036 20.627C424.677 20.627 431.77 23.4346 437.314 29.0498C442.859 34.5934 445.632 41.7577 445.632 50.541C445.632 59.3961 442.859 66.6316 437.314 72.2471C431.77 77.7904 424.677 80.5625 416.036 80.5625C407.323 80.5625 400.194 77.7905 394.649 72.2471C389.105 66.6316 386.332 59.3961 386.332 50.541C386.332 41.7577 389.105 34.5934 394.649 29.0498C400.194 23.4345 407.323 20.627 416.036 20.627ZM587.211 20.627C595.78 20.627 602.369 23.1106 606.978 28.0781C611.658 33.0457 613.998 40.0292 613.998 49.0283C613.998 51.0441 613.926 53.1322 613.782 55.292H574.141C575.869 62.9953 580.838 66.8476 589.047 66.8477C591.999 66.8477 594.627 66.3428 596.932 65.335C599.236 64.2551 601.972 62.3834 605.141 59.7197L613.998 69.8711C606.581 76.9984 598.12 80.5624 588.615 80.5625C579.398 80.5625 572.053 77.8624 566.58 72.4629C561.179 67.0633 558.479 59.8635 558.479 50.8643C558.479 42.0091 561.071 34.7737 566.256 29.1582C571.441 23.4707 578.426 20.627 587.211 20.627ZM243.526 57.8838C243.526 63.5711 246.299 66.415 251.844 66.415C258.612 66.4149 261.997 62.8509 261.997 55.7236V22.5703H278.199V78.7256H263.4V72.7861C260.016 77.9696 254.58 80.5615 247.091 80.5615C240.466 80.5615 235.497 78.9782 232.185 75.8105C228.944 72.6428 227.324 68.1067 227.324 62.2031V22.5703H243.526V57.8838ZM161.807 22.5713H174.444V34.666H161.807V60.9082C161.807 62.7799 162.239 64.1114 163.104 64.9033C163.968 65.6232 165.299 65.9834 167.1 65.9834C168.468 65.9834 170.592 65.6951 173.473 65.1191L175.309 78.0781C170.772 79.446 166.488 80.1299 162.455 80.1299C156.478 80.1299 152.158 78.834 149.493 76.2422C146.901 73.6504 145.604 69.5106 145.604 63.8232V34.666H135.775V22.5713H145.604V6.15625H161.807V22.5713ZM212.189 21.5977C214.422 21.5977 217.482 22.2453 221.37 23.541L218.346 37.7959C214.962 37.004 212.513 36.6084 211.001 36.6084C207.401 36.6085 204.556 38.0126 202.468 40.8203C200.38 43.5561 199.336 47.3357 199.336 52.1592V78.7256H183.134V22.5693H198.147V30.5605C201.172 24.5852 205.853 21.5977 212.189 21.5977ZM374.509 0C378.397 0 382.502 0.647547 386.822 1.94336L384.015 13.9307C381.926 13.4267 379.802 13.1748 377.642 13.1748C375.553 13.1748 374.077 13.6432 373.213 14.5791C372.349 15.4431 371.917 16.9909 371.917 19.2227V22.5703H383.69V34.665H371.917V78.7256H355.715V34.665H346.317V22.5703H355.715V18.5742C355.715 6.19146 361.979 5.23399e-05 374.509 0ZM483.068 21.5977C485.301 21.5977 488.361 22.2453 492.249 23.541L489.225 37.7959C485.84 37.004 483.392 36.6084 481.88 36.6084C478.279 36.6084 475.435 38.0125 473.347 40.8203C471.258 43.5561 470.214 47.3357 470.214 52.1592V78.7256H454.012V22.5693H469.026V30.5605C472.051 24.5853 476.732 21.5977 483.068 21.5977ZM416.036 34.3418C412.076 34.3418 408.871 35.8178 406.423 38.7695C403.975 41.7213 402.75 45.6454 402.75 50.541C402.75 55.5084 403.975 59.4682 406.423 62.4199C408.871 65.3715 412.076 66.8477 416.036 66.8477C419.996 66.8476 423.165 65.3715 425.541 62.4199C427.989 59.4682 429.214 55.5084 429.214 50.541C429.214 45.6454 427.989 41.7213 425.541 38.7695C423.093 35.8179 419.925 34.3418 416.036 34.3418ZM522.447 34.4502C518.775 34.4502 515.787 35.7817 513.482 38.4453C511.25 41.0371 510.134 44.4929 510.134 48.8125C510.134 53.1321 511.286 56.6243 513.59 59.2881C515.894 61.9518 518.847 63.2831 522.447 63.2832C526.12 63.2832 529.109 61.9519 531.413 59.2881C533.717 56.6243 534.869 53.1321 534.869 48.8125C534.869 44.493 533.717 41.0371 531.413 38.4453C529.109 35.7815 526.12 34.4502 522.447 34.4502ZM315.166 33.2617C308.613 33.2619 304.437 36.8258 302.637 43.9531H326.724C325.932 36.8257 322.079 33.2617 315.166 33.2617ZM586.995 33.2617C580.442 33.2617 576.265 36.8257 574.465 43.9531H598.552C597.76 36.8258 593.908 33.2619 586.995 33.2617Z" fill="black"/>
+<defs>
+<clipPath id="clip0_10581_1412">
+<rect width="100" height="100" fill="white"/>
+</clipPath>
+</defs>
+</svg>
diff --git a/docs/ui-sdk/README.md b/docs/ui-sdk/README.md
new file mode 100644
index 000000000..eb0168b50
--- /dev/null
+++ b/docs/ui-sdk/README.md
@@ -0,0 +1,27 @@
+# TrueForge UI SDK — documentation
+
+Mintlify site for `@truefoundry/trueforge-ui`.
+
+## Local development
+
+```bash
+npm i -g mint
+mint dev
+```
+
+Opens at http://localhost:3000. Run `mint broken-links` before publishing.
+
+## Structure
+
+```
+docs.json navigation, theme, branding
+index.mdx landing page
+get-started/ installation, quickstart
+concepts/ architecture, agent modes, server contract
+guides/ layouts, theming, slots, custom server, MCP OAuth, troubleshooting
+reference/ TrueforgeUI, theme, containers, atoms, hooks, server
+images/ logos and screenshots
+snippets/ reusable MDX fragments
+```
+
+See `CLAUDE.md` for authoring conventions and which SDK files are authoritative.
diff --git a/docs/ui-sdk/concepts/agent-modes.mdx b/docs/ui-sdk/concepts/agent-modes.mdx
new file mode 100644
index 000000000..24e100f00
--- /dev/null
+++ b/docs/ui-sdk/concepts/agent-modes.mdx
@@ -0,0 +1,64 @@
+---
+title: "Agent modes"
+description: "Choose between a fixed agent, a library, a composer, or both."
+---
+
+`agentConfig` decides which agent-selection affordances the shell exposes.
+
+```ts
+type AgentConfig =
+ | { mode: "SingleAgent"; name: string }
+ | { mode: "AgentLibrary" }
+ | { mode: "AgentComposer"; defaultAgentSpec?: AgentSpec }
+ | { mode: "AgentLibraryWithComposer"; defaultAgentSpec?: AgentSpec };
+```
+
+The default is `{ mode: "AgentLibraryWithComposer" }`.
+
+| Mode | Library | Composer | New chat |
+| --- | --- | --- | --- |
+| `SingleAgent` | — | — | yes |
+| `AgentLibrary` | yes | — | no |
+| `AgentComposer` | — | yes | yes |
+| `AgentLibraryWithComposer` | yes | yes | yes |
+
+<AccordionGroup>
+ <Accordion title="SingleAgent">
+ Pins the UI to one named agent. All selection controls are hidden and the user cannot
+ switch agents or open the composer.
+ </Accordion>
+ <Accordion title="AgentLibrary">
+ Users pick from agents your `searchAgents` implementation returns, but cannot author a
+ new one. Note that "new chat" is disabled in this mode only.
+ </Accordion>
+ <Accordion title="AgentComposer">
+ Users assemble an ad-hoc agent — model, skills, MCP servers — without browsing a
+ library.
+ </Accordion>
+ <Accordion title="AgentLibraryWithComposer">
+ Both surfaces, and the default. Users can pick an existing agent or author a new one.
+ </Accordion>
+</AccordionGroup>
+
+## Gotchas
+
+<Warning>
+ `defaultAgentSpec` seeds a new draft rather than binding to the current one. Changing it does
+ not alter the conversation on screen, and it does not apply on **clear chat** either — that
+ path deliberately preserves the spec already bound to the draft. The new value is picked up
+ when a **new chat** starts. To apply it immediately, remount the component with a new `key`.
+ It is ignored entirely in `SingleAgent` mode.
+</Warning>
+
+<Warning>
+ Always pass an explicit `defaultAgentSpec` in composer modes. Omitting it falls back to
+ `{ model: { name: "openai-main/gpt-4.1" } }`, and requests fail if your backend does not
+ expose a model under that exact name.
+</Warning>
+
+## Settings
+
+The settings panel appears only when your server exposes a `catalog`. Without one it is
+silently absent — there is no error, so an unexpectedly missing settings button usually means
+the catalog is not attached. Note that `useCatalogServer()` throws when there is no catalog;
+use `useOptionalCatalogServer()` in code that must tolerate its absence.
diff --git a/docs/ui-sdk/concepts/architecture.mdx b/docs/ui-sdk/concepts/architecture.mdx
new file mode 100644
index 000000000..12d74b692
--- /dev/null
+++ b/docs/ui-sdk/concepts/architecture.mdx
@@ -0,0 +1,68 @@
+---
+title: "How it fits together"
+description: "The pieces you compose: providers, layouts, containers, and slots."
+---
+
+You can use the SDK at three levels of control. Most applications stay at the first.
+
+<Steps>
+ <Step title="Drop in TrueforgeUI">
+ One component, a `server` and a `layout`. It mounts everything it needs internally.
+ </Step>
+ <Step title="Supply your own layout">
+ Pass a component to `layout` and arrange the exported containers yourself.
+ </Step>
+ <Step title="Mount the providers yourself">
+ Skip `TrueforgeUI` entirely and compose the providers directly.
+ </Step>
+</Steps>
+
+## Containers and atoms
+
+Two kinds of component are exported, and the distinction determines which one you reach for.
+
+**Containers** are connected to the chat runtime. `ThreadContainer`, `ComposerContainer`, and
+`ThreadListContainer` know how to read messages, stream responses, and switch sessions. They
+take few props because they get their data from context. Use them to assemble a layout.
+
+**Atoms** are presentational. `AssistantMessageBubble`, `ComposerShell`, and `ToolCallCard`
+take everything they render as props and hold no runtime state. You rarely render an atom
+directly — instead you replace one, and the container that renders it picks up your version.
+
+That replacement is what `overrides` does: name a component, supply your own, and it is used
+everywhere that component appears. See [Slot overrides](/ui-sdk/guides/slot-overrides).
+
+## Provider stack
+
+`TrueforgeUI` mounts this for you. You only need it when composing manually:
+
+```tsx
+<SlotsProvider overrides={overrides} theme={theme}>
+ <ServerProvider server={server}>
+ <ShellModeProvider agentConfig={{ mode: "AgentLibrary" }}>
+ <TrueFoundryChatProvider server={server}>
+ <MyLayout />
+ </TrueFoundryChatProvider>
+ </ShellModeProvider>
+ </ServerProvider>
+</SlotsProvider>
+```
+
+Order matters: `SlotsProvider` must be outside `TrueFoundryChatProvider`.
+
+<Warning>
+ Composing manually means you own runtime resets. `TrueforgeUI` remounts the chat runtime
+ when the selected agent changes, a new draft starts, or the chat is cleared; a hand-rolled
+ stack does not. Change the `key` on `TrueFoundryChatProvider` yourself at those moments, or
+ stale messages carry over between agents.
+</Warning>
+
+## Styling hooks
+
+These class names and attributes are stable and safe to target from your own CSS:
+`.aui-root`, `.aui-theme-root`, `.aui-markdown`, `.aui-syntax-highlighter`, `.aui-openui`,
+`.aui-monaco`, plus `data-slot` attributes on individual components. Most slot values are
+prefixed `aui_`, but not all — `avatar`, `tool-call-card`, and `tool-group-card` are among the
+unprefixed ones, so inspect the element rather than assuming the prefix.
+
+For token-level changes, prefer [theming](/ui-sdk/guides/theming) over CSS overrides.
diff --git a/docs/ui-sdk/concepts/server-contract.mdx b/docs/ui-sdk/concepts/server-contract.mdx
new file mode 100644
index 000000000..60878838b
--- /dev/null
+++ b/docs/ui-sdk/concepts/server-contract.mdx
@@ -0,0 +1,314 @@
+---
+title: "Server contract"
+description: "The interfaces a backend must implement for the SDK to talk to it."
+---
+
+The `server` prop accepts either a built-in config object or an object implementing
+`AgentUIServer`.
+
+```ts
+type TrueforgeServerConfig =
+ | {
+ type: "truefoundry";
+ apiKey: string;
+ controlPlaneURL: string;
+ gatewayPlaneURL?: string;
+ catalog?: CatalogServer;
+ }
+ | ({ type: "trueforge"; apiKey: string; catalog?: CatalogServer } & Record<string, unknown>)
+ | AgentUIServer;
+```
+
+Each form resolves differently. An `AgentUIServer` object is used immediately. A `truefoundry`
+config is resolved asynchronously, so the SDK renders a loading indicator (`role="status"`) for
+a moment first. A `trueforge` config is typed for the forthcoming harness adapter and currently
+resolves to a not-implemented error — see [Quickstart](/ui-sdk/get-started/quickstart#trueforge).
+
+`catalog` is optional on both built-in forms and is attached to the resolved server, which is
+how you enable the [settings UI](/ui-sdk/reference/catalog) without hand-building a server.
+
+## The composed contract
+
+```ts
+type AgentUIServer = AgentChatServer & AgentBuilderServer & { catalog?: CatalogServer };
+```
+
+Chat and session operations, agent-builder operations, and an optional settings catalog. Only
+the first two are required.
+
+Every interface is generic. The SDK's types constrain only the fields the UI itself reads, so
+when your backend returns richer objects you widen the type parameters rather than casting or
+stripping fields. See [widening](#widening-the-types) below.
+
+## AgentChatServer
+
+The runtime calls these. All operations are keyed by a flat `sessionId`.
+
+```ts
+interface AgentChatServer {
+ createSession(req: CreateSessionRequest): Promise<Session>;
+ listSessions(req?: ListSessionsParams): Promise<PageResult<Session, ListSessionsResponse>>;
+ getSession(req: { sessionId: string }): Promise<Session>;
+ updateSession(req: UpdateSessionRequest): Promise<Session>;
+
+ createTurn(req: {
+ sessionId: string;
+ input?: TurnInputItem[];
+ previousTurnId?: PreviousTurnIdInput;
+ }): AsyncIterable<TurnStreamData>;
+
+ cancelSession(req: { sessionId: string }): Promise<void>;
+ deleteSession?(req: { sessionId: string }): Promise<void>;
+
+ listTurns(req: {
+ sessionId: string;
+ limit?: number;
+ pageToken?: string;
+ }): Promise<PageResult<Turn, ListTurnsResponse>>;
+ getTurn(req: { sessionId: string; turnId: string }): Promise<Turn>;
+
+ listEvents(req: {
+ sessionId: string;
+ pageToken?: string;
+ lastTurnId?: string;
+ limit?: number;
+ }): Promise<PageResult<SessionEventItem, ListSessionEventsResponse>>;
+
+ subscribeToTurn?(req: {
+ sessionId: string;
+ turnId: string;
+ afterSequenceNumber?: number;
+ }): AsyncIterable<TurnStreamData>;
+
+ downloadSandboxFile?(req: {
+ sessionId: string;
+ turnId: string;
+ sandboxId: string;
+ path: string;
+ }): Promise<Blob>;
+}
+```
+
+Three methods are optional. `deleteSession` gates the delete control in the session list.
+`subscribeToTurn` lets a reconnecting client resume a stream from `afterSequenceNumber` rather
+than replaying it. `downloadSandboxFile` enables artifact downloads.
+
+<Note>
+ `downloadSandboxFile` receives both `turnId` and `sandboxId` because backends address
+ sandboxes differently. If your download route is scoped to a turn, resolve the sandbox from
+ `turnId` and ignore `sandboxId`; if you address sandboxes directly, use `sandboxId`.
+</Note>
+
+`createTurn` and `subscribeToTurn` yield `TurnStreamData`, an envelope of
+`{ sequenceNumber, event }`. The event protocol is documented in
+[Streaming events](/ui-sdk/reference/events).
+
+## Sessions
+
+```ts
+interface Session {
+ id: string;
+ title?: string;
+ agentName?: string;
+ agentSpec?: AgentSpec;
+ isMutable: boolean;
+ createdAt: string;
+ updatedAt: string;
+}
+```
+
+`id`, `isMutable`, `createdAt`, and `updatedAt` are required; timestamps are ISO strings. Set
+`isMutable: true` while the agent spec may still be edited — that is what permits
+`updateSession`.
+
+`CreateSessionRequest` is `{ agentName?, agentSpec?, title? }`; `UpdateSessionRequest` is the
+same plus a required `sessionId`.
+
+## Pagination
+
+```ts
+interface PageResult<T, R = unknown> {
+ data: T[];
+ response: R;
+ hasNextPage(): boolean;
+ getNextPage(): Promise<PageResult<T, R>>;
+}
+```
+
+`PageResult` is an object with methods, not a plain DTO. `data` holds the rows, `response`
+carries your raw backend payload, and the two methods drive paging. Requests accept a
+`pageToken`, so `getNextPage()` is where you call your backend again with the token you held
+onto.
+
+The `response` type parameter is the shape your endpoint returned — `ListSessionsResponse`,
+`ListTurnsResponse`, or `ListSessionEventsResponse`, each `{ data, pagination }` where
+`pagination` is a `TokenPagination` of `{ nextPageToken?, previousPageToken?, limit }`.
+
+```ts
+async listSessions({ pageToken, limit = 20 } = {}) {
+ const res = await fetch(`/api/sessions?limit=${limit}&cursor=${pageToken ?? ""}`);
+ const body = await res.json(); // { data, pagination }
+ return {
+ data: body.data,
+ response: body,
+ hasNextPage: () => Boolean(body.pagination.nextPageToken),
+ getNextPage: () => this.listSessions({ pageToken: body.pagination.nextPageToken, limit }),
+ };
+}
+```
+
+<Note>
+ Because `PageResult` carries methods, you cannot return a bare object literal parsed from
+ JSON. Build it — or write a small helper — so `hasNextPage` and `getNextPage` are present.
+</Note>
+
+## Turn input
+
+What the UI sends into `createTurn`:
+
+```ts
+type TurnInputItem = UserMessage | UserToolApprovalEvent | UserToolResponseEvent;
+
+interface UserMessage {
+ type: "user.message";
+ content: UserMessageContent;
+}
+
+interface UserToolApprovalEvent {
+ type: "user.tool_approval";
+ threadId: string;
+ toolCallId: string;
+ approval: { status: "allow" } | { status: "deny"; reason?: string };
+}
+
+interface UserToolResponseEvent {
+ type: "user.tool_response";
+ threadId: string;
+ toolCallId: string;
+ content: string;
+}
+```
+
+A plain chat message arrives as `user.message`. Approving or rejecting a tool call, and
+answering a prompt the agent raised, arrive as the other two — all three through the same
+`createTurn` entry point, so branch on `type`.
+
+## Turn state
+
+```ts
+interface Turn {
+ id: string;
+ sessionId: string;
+ previousTurnId?: string;
+ input?: TurnInputItem[];
+ state: TurnState;
+ createdAt: string;
+}
+
+type TurnState =
+ | { status: "running" }
+ | { status: "done"; output?: unknown; requiredActions?: unknown[]; completedAt: string }
+ | { status: "cancelled"; reason: string; completedAt: string }
+ | { status: "error"; message: string; completedAt: string };
+```
+
+A turn ends in one of three terminal states, each carrying `completedAt`. A `done` turn may
+still carry `requiredActions` — that is how a turn signals it is waiting on the user, such as a
+tool approval, rather than being finished outright. The user's reply arrives on the next
+`createTurn` call as a `user.tool_approval` or `user.tool_response` input item.
+
+## AgentBuilderServer
+
+Powers the agent library and the draft composer.
+
+```ts
+interface AgentBuilderServer {
+ getModels(): Promise<ModelSelection[]>;
+ getSkills(): Promise<AgentSkill[]>;
+ getMcp(): Promise<ConnectorState[]>;
+ searchAgents(req?: SearchAgentsParams): Promise<AgentLibraryEntry[]>;
+ saveAgent(req: SaveAgentRequest): Promise<unknown>;
+ deleteAgent?(req: { agentName: string }): Promise<void>;
+}
+```
+
+These return picker rows — the minimum each selector renders:
+
+| Type | Required | Optional |
+| --- | --- | --- |
+| `ModelSelection` | `name`, `provider` | `reasoningEfforts?: string[]` |
+| `AgentSkill` | `id`, `name` | `description` |
+| `ConnectorState` | `id`, `name` | `description`, `requiresAuth`, `authenticated` |
+| `AgentLibraryEntry` | `name` | `agentId`, `agentSpec` |
+
+<Note>
+ Return a non-empty `reasoningEfforts` on a `ModelSelection` and the UI shows a
+ reasoning-effort picker beside the model selector. On `AgentLibraryEntry`, supply `agentSpec`
+ to enable Edit — omit it for try-only agents — and `agentId` when the stable id differs from
+ the display `name`, which otherwise serves as the id.
+</Note>
+
+`SearchAgentsParams` is `{ query?, limit?, offset? }` — offset paging, since it backs a search
+box rather than an infinite list. `SaveAgentRequest` is `{ agentName, agentSpec }`, and its
+return value is passed through untyped.
+
+## AgentSpec
+
+```ts
+interface AgentSpec {
+ model: Model;
+ instructions?: string;
+ skills?: SkillMount[];
+ mcpServers?: McpServerMount[];
+}
+
+interface Model {
+ name: string;
+ params?: { maxTokens?: number; reasoningEffort?: string };
+}
+```
+
+Only `model` is required. `instructions` carries the system prompt.
+
+`SkillMount` and `McpServerMount` are typed as `object`. The runtime stores and forwards mounts
+without reading any field, and your backend owns their shape — so the base constrains only that
+a mount is an object, and you intersect your concrete type over it.
+
+## Widening the types
+
+Every interface takes type parameters defaulting to the SDK-minimal shapes. Supply your own to
+carry extra fields through the UI without casting:
+
+```ts
+interface MyModel extends ModelSelection {
+ modelId: string;
+ pricePerMillionTokens: number;
+}
+
+type MySkillMount = { fqn: string; preload: boolean };
+type MySpec = AgentSpec<Model, MySkillMount>;
+
+const server: AgentUIServer<AgentChatServer<MySpec>, AgentBuilderServer<MySpec, MyModel>> = {
+ /* ... */
+};
+```
+
+The UI keeps reading only the fields it knows about; your own components — supplied through
+[slot overrides](/ui-sdk/guides/slot-overrides) — can read the rest.
+
+## Next
+
+<CardGroup cols={2}>
+ <Card title="Worked implementation" icon="server" href="/ui-sdk/guides/custom-server">
+ A minimal `AgentUIServer` you can copy.
+ </Card>
+ <Card title="Streaming events" icon="bolt" href="/ui-sdk/reference/events">
+ The event protocol `createTurn` yields.
+ </Card>
+ <Card title="Settings catalog" icon="sliders" href="/ui-sdk/reference/catalog">
+ The optional `catalog` port behind the settings UI.
+ </Card>
+ <Card title="Type reference" icon="code" href="/ui-sdk/reference/server">
+ Every exported server type.
+ </Card>
+</CardGroup>
diff --git a/docs/ui-sdk/get-started/installation.mdx b/docs/ui-sdk/get-started/installation.mdx
new file mode 100644
index 000000000..b8d6cba1e
--- /dev/null
+++ b/docs/ui-sdk/get-started/installation.mdx
@@ -0,0 +1,102 @@
+---
+title: "Installation"
+description: "Install the SDK, import the stylesheet, and satisfy peer dependencies."
+---
+
+## Install
+
+<CodeGroup>
+
+```bash npm
+npm install @truefoundry/trueforge-ui
+```
+
+```bash pnpm
+pnpm add @truefoundry/trueforge-ui
+```
+
+```bash yarn
+yarn add @truefoundry/trueforge-ui
+```
+
+</CodeGroup>
+
+`react` and `react-dom` are required peer dependencies and must be version 18 or 19.
+`@assistant-ui/core`, `@assistant-ui/react`, and `@types/react` are optional peers — the package
+bundles working versions, so install them yourself only if you use their APIs directly or need
+to pin a version. The package is ESM-only and client-only.
+
+## Import the stylesheet
+
+The SDK ships a prebuilt stylesheet. Import it after Tailwind in your host CSS:
+
+```css title="app.css"
+@import "tailwindcss";
+@import "@truefoundry/trueforge-ui/styles.css";
+```
+
+`@truefoundry/trueforge-ui/styles.css` is the only stylesheet path you should reference. It is
+self-contained — the SDK's own components are styled without any Tailwind setup on your side.
+
+It deliberately omits Tailwind preflight so it cannot clobber your app's base styles. The
+`@import "tailwindcss"` line above is therefore for *your* styles, not the SDK's; drop it if
+your app does not use Tailwind.
+
+The stylesheet also brings in markdown styles scoped to `.markdown-body`, plus the semantic
+design tokens. Note that most tokens are applied as inline styles at runtime, so overriding them
+from your own CSS will not work — change them through `theme.tokens` instead. See
+[Theming](/ui-sdk/guides/theming#precedence).
+
+## Deduplicate the assistant-ui singletons
+
+`react`, `react-dom`, `@assistant-ui/core`, `@assistant-ui/react`, and `@assistant-ui/store`
+must each resolve to exactly one copy in your bundle. Two copies produce a runtime error
+along the lines of *"requires an AuiProvider"*.
+
+<CodeGroup>
+
+```ts vite.config.ts
+export default defineConfig({
+ resolve: {
+ dedupe: [
+ "react",
+ "react-dom",
+ "@assistant-ui/core",
+ "@assistant-ui/react",
+ "@assistant-ui/store",
+ ],
+ },
+});
+```
+
+```json package.json
+{
+ "resolutions": {
+ "@assistant-ui/core": "<version>",
+ "@assistant-ui/store": "<version>"
+ }
+}
+```
+
+</CodeGroup>
+
+The `vite.config.ts` approach is usually enough. Reach for `resolutions` (or `overrides` on
+npm, `pnpm.overrides` on pnpm) when a transitive dependency drags in a second copy.
+
+Note that `@assistant-ui/store` arrives transitively through `@assistant-ui/core` rather than
+being declared by the SDK, so there is no published version to look up — pin it to whatever your
+lockfile resolves `@assistant-ui/core` against.
+
+## Give the component a height
+
+The SDK fills its parent container and does not set its own height. A parent with no
+resolved height collapses the entire chat UI, which is the single most common cause of a
+"blank" first install.
+
+```tsx
+<div className="flex h-dvh min-h-0 w-full flex-1 flex-col">
+ <TrueforgeUI /* ... */ className="h-full min-h-0" />
+</div>
+```
+
+Next: [Quickstart](/ui-sdk/get-started/quickstart).
diff --git a/docs/ui-sdk/get-started/quickstart.mdx b/docs/ui-sdk/get-started/quickstart.mdx
new file mode 100644
index 000000000..20f7cd785
--- /dev/null
+++ b/docs/ui-sdk/get-started/quickstart.mdx
@@ -0,0 +1,134 @@
+---
+title: "Quickstart"
+description: "Render a working agent chat UI against one of three backends."
+---
+
+Make sure you have completed [Installation](/ui-sdk/get-started/installation) first — the stylesheet
+import and the height requirement both matter, and skipping either produces a blank screen.
+
+Then pick a backend. The `server` prop takes one of three shapes, and everything else about the
+component is identical between them.
+
+<CardGroup cols={3}>
+ <Card title="TrueFoundry" icon="bolt" href="#truefoundry">
+ Zero config. Point at a control plane and go.
+ </Card>
+ <Card title="TrueForge" icon="clock" href="#trueforge">
+ Harness adapter. Coming soon.
+ </Card>
+ <Card title="Custom" icon="wrench" href="#custom">
+ Compose or implement the server yourself.
+ </Card>
+</CardGroup>
+
+## TrueFoundry
+
+The zero-config path. The SDK builds the agent UI server from your API key and control plane
+URL; the gateway URL is optional and resolved from the control plane when omitted.
+
+```tsx title="App.tsx"
+import { TrueforgeUI } from "@truefoundry/trueforge-ui";
+
+export default function App() {
+ return (
+ <div style={{ height: "100dvh" }}>
+ <TrueforgeUI
+ server={{
+ type: "truefoundry",
+ apiKey: {{API_KEY}},
+ controlPlaneURL: {{CONTROL_PLANE_URL}},
+ }}
+ layout="sidebar"
+ />
+ </div>
+ );
+}
+```
+
+Add `gatewayPlaneURL` alongside `controlPlaneURL` to target a specific gateway.
+
+Because this config is resolved asynchronously, the SDK shows a brief loading indicator before
+the chat appears. The other two paths mount immediately.
+
+## TrueForge
+
+Typed for hosts adopting the harness adapter.
+
+```tsx
+<TrueforgeUI
+ server={{
+ type: "trueforge",
+ apiKey: {{API_KEY}},
+ }}
+ layout="sidebar"
+/>
+```
+
+<Warning>
+ The harness adapter has not shipped yet. Selecting this type surfaces a not-implemented error
+ and calls `onError` rather than rendering a chat, so use
+ [TrueFoundry](#truefoundry) or a [custom server](#custom) until the adapter lands.
+</Warning>
+
+## Custom
+
+Use this when you compose chat and builder yourself — a chat-only gateway adapter with a stub
+catalog, a full host BFF, or a proxy that keeps credentials server-side. Pass the server object
+directly, with no `type` wrapper.
+
+`createTrueFoundryServer` combines a chat port with the builder callbacks. The stubs below
+return empty lists, which is enough to mount; fill them in as you add agent management.
+
+```tsx title="App.tsx"
+import { TrueforgeUI, createTrueFoundryServer } from "@truefoundry/trueforge-ui";
+import { createTrueFoundryChatServer } from "@truefoundry/assistant-ui-runtime/plugins/truefoundry-agent-server-adapter";
+
+// this structure will most likely change. Govinda to update this
+const chatServer = createTrueFoundryChatServer({
+ apiKey: import.meta.env.VITE_TFY_API_KEY,
+ baseUrl: import.meta.env.VITE_TFY_GATEWAY_URL,
+});
+
+const server = createTrueFoundryServer({
+ chatServer,
+ getModels: async () => [],
+ getSkills: async () => [],
+ getMcp: async () => [],
+ searchAgents: async () => [],
+ saveAgent: async () => ({}),
+});
+
+export default function App() {
+ return (
+ <div style={{ height: "100dvh" }}>
+ <TrueforgeUI server={server} layout="sidebar" />
+ </div>
+ );
+}
+```
+
+Two notes on this path. Empty `getModels` means the composer has no models to offer, so supply
+real ones before enabling composer mode — see [Agent modes](/ui-sdk/concepts/agent-modes). And
+`createTrueFoundryServer` attaches no `catalog`, so the settings panel stays hidden until you
+pass one.
+
+To skip `createTrueFoundryServer` entirely and implement the interface from scratch — against
+any backend, not just TrueFoundry — see
+[Bring your own server](/ui-sdk/guides/custom-server).
+
+## Where to go next
+
+<CardGroup cols={2}>
+ <Card title="Pick a layout" icon="table-columns" href="/ui-sdk/guides/layouts">
+ Sidebar, drawer, dock, widget, or a layout you write yourself.
+ </Card>
+ <Card title="Match your brand" icon="palette" href="/ui-sdk/guides/theming">
+ Presets, semantic tokens, logo, and dark mode.
+ </Card>
+ <Card title="Swap components" icon="puzzle-piece" href="/ui-sdk/guides/slot-overrides">
+ Replace any built-in component via `overrides`.
+ </Card>
+ <Card title="Server contract" icon="server" href="/ui-sdk/concepts/server-contract">
+ Every interface a backend must satisfy.
+ </Card>
+</CardGroup>
diff --git a/docs/ui-sdk/guides/custom-server.mdx b/docs/ui-sdk/guides/custom-server.mdx
new file mode 100644
index 000000000..15e2d7433
--- /dev/null
+++ b/docs/ui-sdk/guides/custom-server.mdx
@@ -0,0 +1,229 @@
+---
+title: "Bring your own server"
+description: "Implement AgentUIServer and pass the object straight to the component."
+---
+
+Because `server` accepts an `AgentUIServer` directly, you can front any backend — including
+your own proxy that keeps API keys server-side. The object is used immediately, so there is no
+loading indicator on mount.
+
+## Minimal implementation
+
+The shape below is the smallest thing that mounts. Optional methods are omitted; required ones
+must exist even if they only throw in paths your UI never reaches.
+
+List methods return a `PageResult`, which carries methods as well as data — so a small helper
+for the single-page case keeps the boilerplate in one place.
+
+```ts title="server.ts"
+import type { AgentUIServer, PageResult, Session } from "@truefoundry/trueforge-ui";
+
+function onePage<T>(data: T[]): PageResult<T> {
+ return {
+ data,
+ response: undefined,
+ hasNextPage: () => false,
+ getNextPage: () => Promise.reject(new Error("no more pages")),
+ };
+}
+
+const now = new Date().toISOString();
+const session: Session = {
+ id: "s1",
+ isMutable: true,
+ createdAt: now,
+ updatedAt: now,
+};
+
+export const server: AgentUIServer = {
+ // chat
+ async createSession() {
+ return session;
+ },
+ async listSessions() {
+ return onePage([session]);
+ },
+ async getSession() {
+ return session;
+ },
+ async updateSession() {
+ return session;
+ },
+ async *createTurn({ sessionId, input }) {
+ const res = await fetch(`/api/sessions/${sessionId}/turns`, {
+ method: "POST",
+ body: JSON.stringify({ input }),
+ });
+ let seq = 0;
+ for await (const event of parseEventStream(res)) {
+ yield { sequenceNumber: seq++, event };
+ }
+ },
+ async cancelSession({ sessionId }) {
+ await fetch(`/api/sessions/${sessionId}/cancel`, { method: "POST" });
+ },
+ async listTurns() {
+ return onePage([]);
+ },
+ async getTurn({ turnId }) {
+ throw new Error(`unknown turn ${turnId}`);
+ },
+ async listEvents() {
+ return onePage([]);
+ },
+
+ // builder
+ async getModels() {
+ return [{ name: "my-model", provider: "my-provider" }];
+ },
+ async getSkills() {
+ return [];
+ },
+ async getMcp() {
+ return [];
+ },
+ async searchAgents() {
+ return [{ name: "support-agent" }];
+ },
+ async saveAgent() {
+ return {};
+ },
+};
+```
+
+```tsx title="App.tsx"
+<TrueforgeUI server={server} layout="sidebar" agentConfig={{ mode: "AgentLibrary" }} />
+```
+
+## Streaming
+
+`createTurn` yields envelopes of the form `{ sequenceNumber, event }` — not bare events. The
+number must increase monotonically within the turn, and it is what lets a reconnecting client
+resume via `subscribeToTurn({ afterSequenceNumber })`.
+
+The minimum viable stream for one assistant reply is three events:
+
+```ts
+async *createTurn({ sessionId, input }) {
+ const turnId = crypto.randomUUID();
+ const threadId = sessionId;
+ let seq = 0;
+ const at = () => new Date().toISOString();
+
+ yield {
+ sequenceNumber: seq++,
+ event: { type: "turn.created", id: crypto.randomUUID(), turnId, createdAt: at() },
+ };
+
+ // stream text as it arrives; reuse one message id across all deltas
+ const messageId = crypto.randomUUID();
+ for await (const piece of myModelStream(input)) {
+ yield {
+ sequenceNumber: seq++,
+ event: {
+ type: "model.message.delta",
+ id: messageId,
+ threadId,
+ content: piece, // the increment, not the running total
+ },
+ };
+ }
+
+ yield {
+ sequenceNumber: seq++,
+ event: {
+ type: "turn.done",
+ id: crypto.randomUUID(),
+ state: { status: "done", completedAt: at() },
+ createdAt: at(),
+ },
+ };
+}
+```
+
+Two things are easy to get wrong. Deltas carry the *increment* rather than the accumulated
+text, and every delta for one message shares a single `id`. And a stream that ends without a
+`turn.done` leaves the UI showing the turn as still running.
+
+[Streaming events](/ui-sdk/reference/events) documents the full protocol — tool calls, approval
+prompts, sub-agent threads, and sandbox artifacts.
+
+## Pagination
+
+`PageResult<T, R>` carries `data` (the rows), `response` (your raw backend payload), and the
+methods `hasNextPage()` and `getNextPage()`. Page tokens travel the other way: requests accept
+a `pageToken`, so `getNextPage()` calls your backend again with the token you kept.
+
+```ts
+async listSessions({ pageToken, limit = 20 } = {}) {
+ const res = await fetch(`/api/sessions?limit=${limit}&cursor=${pageToken ?? ""}`);
+ const body = await res.json(); // { data, pagination }
+ return {
+ data: body.data,
+ response: body,
+ hasNextPage: () => Boolean(body.pagination.nextPageToken),
+ getNextPage: () => this.listSessions({ pageToken: body.pagination.nextPageToken, limit }),
+ };
+}
+```
+
+Because the result carries methods, you cannot hand back a bare parsed JSON object — construct
+it, or reuse a helper like the `onePage` above.
+
+`listEvents` additionally accepts `lastTurnId`, used when hydrating history for an existing
+session.
+
+## Optional capabilities
+
+<AccordionGroup>
+ <Accordion title="deleteSession / deleteAgent">
+ In a hand-written `AgentUIServer` like the one above, omitting these leaves the
+ corresponding affordances unavailable rather than broken. (This differs from
+ `createTrueFoundryServer`, where an omitted `deleteAgent` throws when called.)
+ </Accordion>
+ <Accordion title="downloadSandboxFile">
+ Return a `Blob`. Required only if your agents produce sandbox artifacts users should be able
+ to download.
+ </Accordion>
+ <Accordion title="subscribeToTurn">
+ Resumes a live stream from `afterSequenceNumber`, so a reconnecting client picks up where it
+ left off instead of replaying the turn. Skip it if your backend cannot resume.
+ </Accordion>
+ <Accordion title="catalog">
+ Attach a [`CatalogServer`](/ui-sdk/reference/catalog) to enable the settings UI — models,
+ connectors, skills, and sandboxes. Without it those surfaces do not render.
+ </Accordion>
+</AccordionGroup>
+
+## Widening the types
+
+The interfaces are generic so you can carry backend-specific fields through the UI without
+casting. `AgentUIServer` takes the chat port, the builder port, and the catalog:
+
+```ts
+interface MyModel extends ModelSelection {
+ modelId: string;
+}
+
+type MySkillMount = { fqn: string; preload: boolean };
+type MySpec = AgentSpec<Model, MySkillMount>;
+
+const server: AgentUIServer<
+ AgentChatServer<MySpec>,
+ AgentBuilderServer<MySpec, MyModel>
+> = {
+ /* ... */
+};
+```
+
+See [Widening the types](/ui-sdk/concepts/server-contract#widening-the-types) for the full set of
+parameters.
+
+## Attachments
+
+Attachment handling defaults to `trueFoundryAttachmentAdapter`. Override it through the
+`adapters` prop on `TrueforgeUI` if your backend stores uploads differently.
+
+```tsx
+<TrueforgeUI server={server} layout="sidebar" adapters={{ attachments: myAdapter }} />
+```
diff --git a/docs/ui-sdk/guides/layouts.mdx b/docs/ui-sdk/guides/layouts.mdx
new file mode 100644
index 000000000..6f9d61aee
--- /dev/null
+++ b/docs/ui-sdk/guides/layouts.mdx
@@ -0,0 +1,101 @@
+---
+title: "Layouts"
+description: "The four built-in layouts, and how to supply your own."
+---
+
+`layout` is required. Pass one of the built-in names or your own component.
+
+<Tabs>
+ <Tab title="sidebar">
+ Full-page chat with a persistent thread list on the left. The default choice for a
+ dedicated chat surface.
+
+ ```tsx
+ <TrueforgeUI server={server} layout="sidebar" />
+ ```
+ </Tab>
+ <Tab title="drawer">
+ Thread list collapses into an overlay drawer. Suited to narrower viewports.
+
+ ```tsx
+ <TrueforgeUI server={server} layout="drawer" />
+ ```
+ </Tab>
+ <Tab title="dock">
+ A panel pinned to the right edge, filling the available width up to a 400px cap. The side is
+ not configurable.
+
+ ```tsx
+ <TrueforgeUI server={server} layout="dock" />
+ ```
+ </Tab>
+ <Tab title="widget">
+ Floating launcher that expands into a compact chat panel.
+
+ ```tsx
+ <TrueforgeUI server={server} layout="widget" />
+ ```
+ </Tab>
+</Tabs>
+
+Built-in layouts are code-split, so naming one does not pull the other three into your bundle.
+A placeholder renders for the moment it takes to load.
+
+`dock` and `widget` are compact layouts: rather than showing the thread list beside the
+conversation, they stack the two and let the user switch between them from a history control.
+`sidebar` and `drawer` keep the list available alongside the chat.
+
+## Custom layouts
+
+Pass a component instead of a string. It renders inside the full provider stack, so every
+container hook and `useSlot` lookup works normally.
+
+```tsx
+import { Thread, ThreadListContainer, TrueforgeUI } from "@truefoundry/trueforge-ui";
+
+function MyLayout() {
+ return (
+ <div className="flex h-full min-h-0">
+ <aside className="w-72 shrink-0 border-r">
+ <ThreadListContainer />
+ </aside>
+ <main className="min-h-0 flex-1">
+ <Thread />
+ </main>
+ </div>
+ );
+}
+
+<TrueforgeUI server={server} layout={MyLayout} />;
+```
+
+`Thread` is a convenience wrapper equal to
+`<ThreadContainer composer={<ComposerContainer />} />`. Split them apart when you need the
+composer somewhere other than directly beneath the transcript.
+
+<Warning>
+ The settings panel is part of the built-in layouts, so a custom layout does not get one. If
+ you need settings, either stay on a built-in layout or build your own panel against the
+ `catalog` server — see [Server](/ui-sdk/reference/server).
+</Warning>
+
+## Composing without TrueforgeUI
+
+For maximum control, mount the providers yourself. Order matters — `SlotsProvider` must be
+outside `TrueFoundryChatProvider`.
+
+```tsx
+<SlotsProvider overrides={overrides} theme={theme}>
+ <ServerProvider server={server}>
+ <ShellModeProvider agentConfig={{ mode: "AgentLibrary" }}>
+ <TrueFoundryChatProvider server={server}>
+ <MyLayout />
+ </TrueFoundryChatProvider>
+ </ShellModeProvider>
+ </ServerProvider>
+</SlotsProvider>
+```
+
+This path gives up the automatic runtime reset that `TrueforgeUI` performs when the selected
+agent changes, so you become responsible for remounting `TrueFoundryChatProvider` — change its
+`key` — at those moments.
diff --git a/docs/ui-sdk/guides/mcp-oauth.mdx b/docs/ui-sdk/guides/mcp-oauth.mdx
new file mode 100644
index 000000000..8dace8e00
--- /dev/null
+++ b/docs/ui-sdk/guides/mcp-oauth.mdx
@@ -0,0 +1,86 @@
+---
+title: "MCP OAuth"
+description: "The two connector authorization flows and the callback route they need."
+---
+
+There are two separate MCP authorization flows in the SDK, and they work differently. Confusing
+them is the usual reason a callback route behaves unexpectedly.
+
+## In-chat: the agent needs a connector mid-turn
+
+When a running agent hits a connector the user has not authorized, the turn pauses and the
+composer renders an auth prompt listing the servers involved.
+
+This flow is deliberately simple. Clicking Connect opens the server's `authUrl` in a **new
+tab** — no popup channel, no callback plumbing on your side. The user authorizes there, returns
+to your app, and presses Continue, which resumes the paused turn. Nothing about this path
+requires a callback route.
+
+```ts
+import { useComposerPauseView } from "@truefoundry/trueforge-ui";
+
+const { kind } = useComposerPauseView(); // "mcp" | "ask-user" | "compose"
+```
+
+`kind === "mcp"` means the composer is blocked on connector authorization.
+`threadHasPendingMcpAuth(state)` is the standalone predicate behind it if you already hold
+thread state.
+
+Override the `McpAuthPrompt` slot to change how the prompt looks. It receives `servers`,
+`onConnect`, `onContinue`, and `readOnly`.
+
+## Settings panel: connecting a connector directly
+
+Authorizing a connector from the settings panel is the flow with the popup and the callback
+route. It runs through `catalog.connectorCatalog.authenticateConnector` and requires a
+[catalog server](/ui-sdk/reference/catalog).
+
+```ts
+import { useMCPAuth, MCP_AUTH_POPUP_CHANNEL } from "@truefoundry/trueforge-ui";
+
+const auth = useMCPAuth({ callbackPath: "/mcp-callback" });
+```
+
+The SDK builds a redirect URL against `callbackPath` — or the current URL when you omit it —
+carrying three parameters:
+
+| Parameter | Set by | Purpose |
+| --- | --- | --- |
+| `screenType=mcp-auth` | SDK | Marks the route as the OAuth completion screen. |
+| `integrationId` | SDK | Which connector is being authorized. |
+| `pUid` | SDK | Correlates the popup with the window that opened it. |
+| `isSuccess` | your provider | Read back on return to report success or failure. |
+
+That URL is passed to `authenticateConnector` as `redirectURL`. If the connector is already
+authenticated the flow short-circuits; otherwise the returned `authorization_endpoint` is opened
+in a popup. When the popup lands on your callback route it posts a message over a
+`BroadcastChannel` named by `MCP_AUTH_POPUP_CHANNEL` (`"truefoundry-mcp-auth-popup"`), and the
+opener runs your callback.
+
+## The callback route
+
+Render the completion screen on the route you named in `callbackPath`:
+
+```tsx title="routes/mcp-callback.tsx"
+import { PostMcpOauthScreen } from "@truefoundry/trueforge-ui";
+
+export default function McpCallback() {
+ return <PostMcpOauthScreen />;
+}
+```
+
+<Warning>
+ Whenever `screenType=mcp-auth` is present in the URL, `TrueforgeUI` renders **only** the OAuth
+ completion screen — no layout, no chat. This applies to any route that mounts the component,
+ so keep the callback on its own route.
+</Warning>
+
+## Server side
+
+The connectors offered to a draft come from `getMcp()` on your `AgentBuilderServer`, which
+returns `ConnectorState[]`. Each carries optional `requiresAuth` and `authenticated` flags.
+
+Managing connectors — adding, editing, authorizing, disconnecting — is the settings surface
+backed by `catalog.connectorCatalog`, where `authenticateConnector` returns either an
+authenticated connector or a result carrying `authorization_endpoint`. See
+[Settings catalog](/ui-sdk/reference/catalog).
diff --git a/docs/ui-sdk/guides/slot-overrides.mdx b/docs/ui-sdk/guides/slot-overrides.mdx
new file mode 100644
index 000000000..173d25879
--- /dev/null
+++ b/docs/ui-sdk/guides/slot-overrides.mdx
@@ -0,0 +1,106 @@
+---
+title: "Slot overrides"
+description: "Replace any built-in atom with your own component."
+---
+
+Pass an `overrides` object to replace a built-in component. Your version is used everywhere
+that component appears, without you having to find each place it is rendered.
+
+```tsx
+import { TrueforgeUI, type AssistantMessageBubbleProps } from "@truefoundry/trueforge-ui";
+
+function MyBubble({ children, error, actionBar, className }: AssistantMessageBubbleProps) {
+ return (
+ <div className={className} data-testid="my-bubble">
+ {error}
+ <div className="prose">{children}</div>
+ {actionBar}
+ </div>
+ );
+}
+
+<TrueforgeUI
+ server={server}
+ layout="sidebar"
+ overrides={{ AssistantMessageBubble: MyBubble }}
+/>;
+```
+
+`SlotOverrides` is `Partial<AtomSlots>`, so overrides are type-checked against the default
+component's signature. Import the exported `*Props` type for the slot you are replacing and
+honor the props you receive — several are rendered nodes (`actionBar`, `error`,
+`approvalSlot`) that the container supplies and expects you to place.
+
+## Commonly overridden slots
+
+<AccordionGroup>
+ <Accordion title="Messages and content">
+ `AssistantMessageBubble`, `UserMessageBubble`, `UserMessageEdit`,
+ `UserMessageActionBar`, `MessageActionBar`, `MessageErrorBanner`, `MessageIndicator`,
+ `MessageTimestamp`, `MessageGroup`, `Markdown`, `SyntaxHighlighter`, `OpenUiFenceBlock`,
+ `CodeEditor`, `MonacoEditorCore`, `WelcomeScreen`.
+ </Accordion>
+ <Accordion title="Composer">
+ `ComposerShell`, `ComposerLeftSection`, `ComposerRightSection`, `ComposerSendButton`,
+ `AttachmentCard`, `AttachmentPickerButton`, `AttachmentPreviewDialog`.
+
+ The draft composer has its own slots — `DraftComposerLeftSection`,
+ `DraftComposerRightSection`, `DraftModelSelector`, and `DraftCompositeSelector` — so you can
+ restyle the draft chrome without touching the standard composer.
+
+ The two sets interact. In a mutable draft the container substitutes the draft sections
+ behind `ComposerLeftSection` / `ComposerRightSection`, but only while those slots are still
+ at their defaults. Override either one and yours wins in draft mode too, which means the
+ model and composite selectors disappear unless you render them yourself.
+ </Accordion>
+ <Accordion title="Thread shell and list">
+ `ThreadRootShell`, `ThreadViewportShell`, `ThreadComposerAreaShell`,
+ `ScrollToBottomButton`, `MessageListSkeleton`, `HistoryLoader`, `ThreadListShell`,
+ `ThreadListNewButton`, `ThreadListRow`, `ThreadListRowSkeleton`,
+ `ThreadListEmptyState`.
+ </Accordion>
+ <Accordion title="Tools and prompts">
+ `ToolCallCard`, `ToolCallContentBlock`, `ToolApprovalBar`, `ToolGroupCard`,
+ `SubAgentCard`, `SandboxToolCallCard`, `SandboxArtifactDownload`, `ChatFileDownload`,
+ `AgentStepsCard`, and the prompt slots `AskUserPrompt`, `McpAuthPrompt`, `ReasoningCard`.
+ </Accordion>
+ <Accordion title="Agent library and shell">
+ `AgentsLibrary`, `AgentsLibraryButton`, `SaveAgentButton`, `SelectAgentEmptyState`,
+ `ClearChatButton`, `Toast`, `ToastStack`, `Accordion`, `AccordionSummary`,
+ `AccordionDetails`.
+ </Accordion>
+</AccordionGroup>
+
+<Note>
+ `SlotOverrides` is derived directly from the SDK's default slot table, so autocomplete on the
+ `overrides` object is an exact list of what can be overridden — nothing more, nothing less.
+</Note>
+
+<Note>
+ Some slots are override-only, meaning you supply your own component rather than wrapping a
+ default: `AskUserPrompt`, `McpAuthPrompt`, and `ReasoningCard` publish their prop types but
+ not the components, and `Accordion`, `AccordionSummary`, and `AccordionDetails` publish
+ neither.
+</Note>
+
+<Note>
+ `Button` and `IconButton` publish their prop types for typing your own components. The
+ buttons themselves are restyled through semantic tokens and CSS rather than replaced — see
+ [Theming](/ui-sdk/guides/theming).
+</Note>
+
+## Discovering slot names
+
+`SlotOverrides` is a mapped type over every slot, so your editor autocompletes the available
+names as you type inside the `overrides` object, and hovering a name shows the component
+signature you need to match. That is the fastest way to find a slot. The groups above list the
+ones most applications touch.
+
+## Overriding outside TrueforgeUI
+
+If you compose providers manually, pass overrides to `SlotsProvider` and keep it outside
+`TrueFoundryChatProvider`:
+
+```tsx
+<SlotsProvider overrides={{ ThreadListRow: MyRow }}>{/* ... */}</SlotsProvider>
+```
diff --git a/docs/ui-sdk/guides/theming.mdx b/docs/ui-sdk/guides/theming.mdx
new file mode 100644
index 000000000..f9b7bed79
--- /dev/null
+++ b/docs/ui-sdk/guides/theming.mdx
@@ -0,0 +1,134 @@
+---
+title: "Theming"
+description: "Presets, semantic tokens, branding, and dark mode."
+---
+
+Theming works the way shadcn/ui theming works: semantic tokens compiled to CSS custom
+properties. `ThemeProvider` writes them as inline styles on a wrapper `div.aui-theme-root`,
+tagged with `data-theme` and `data-preset`.
+
+## The theme object
+
+```ts
+type ThemeConfig = {
+ preset?: "truefoundry" | "claude" | "chatgpt" | "gemini"; // default "truefoundry"
+ mode?: "light" | "dark" | "system";
+ tokens?: Partial<SemanticTokens>;
+ brand?: BrandConfig;
+ className?: string;
+ icons?: IconMap;
+ classNames?: ContentClassNames;
+};
+```
+
+```tsx
+<TrueforgeUI
+ server={server}
+ layout="sidebar"
+ theme={{
+ preset: "claude",
+ tokens: { primary: "#0B5FFF", composerRadius: "1rem" },
+ brand: { name: "Acme", icon: { src: "/logo.svg", alt: "Acme" } },
+ }}
+/>
+```
+
+## Precedence
+
+The provider resolves the preset for the current mode, merges your `theme.tokens` over it, and
+writes the result as **inline styles** on the theme root. So within `theme.tokens`, your entries
+beat the preset — that part is straightforward.
+
+<Warning>
+ Because those tokens land as inline styles, a `:root { --primary: … }` rule in your own CSS
+ will **not** override them. This applies to every token a preset defines, whether or not you
+ passed `theme.tokens`. Use `theme.tokens` to change these, not CSS.
+</Warning>
+
+A few tokens are absent from the presets — `scrollbarThumb`, `assistantBubble`, and
+`assistantBubbleForeground`. Those are not written inline unless you set them, so they fall
+through to the stylesheet's low-precedence layer and a host `:root` rule does take effect.
+
+`theme.className` is applied to the theme root, for utility-class adjustments alongside the
+tokens.
+
+<Note>
+ `brand`, `icons`, and `classNames` are not part of this cascade — they are separate context
+ values, not tokens that layer over one another.
+</Note>
+
+## Light and dark mode
+
+Omit `theme.mode` and the provider is uncontrolled: it resolves `system`, lets the user
+toggle, and persists the choice to `localStorage` under `aui-theme-preference`. Pass
+`theme.mode` and the provider becomes controlled — `setTheme` from `useTheme()` becomes a
+no-op and you own the state.
+
+<Warning>
+ Dark mode toggles the `dark` class on `document.documentElement`. If your app already
+ manages dark mode by the same mechanism, the two will fight. Pass a controlled
+ `theme.mode` derived from your own state to keep them in sync.
+</Warning>
+
+## Reading theme state
+
+```tsx
+import { useTheme, useThemeMode, useBrand } from "@truefoundry/trueforge-ui";
+
+const { preset, mode, preference, isDark, setTheme } = useTheme();
+const resolved = useThemeMode(); // "light" | "dark", defaults to "light" outside a provider
+const brand = useBrand();
+```
+
+`BrandLogo` and `BrandIcon` render `theme.brand.logo` and `theme.brand.icon`. Their fallbacks
+differ: `BrandLogo` falls back to a default mark plus the brand name (default `"TrueFoundry"`),
+while `BrandIcon` falls back to the bare mark with no name.
+
+## Token naming
+
+`SemanticTokens` keys map to the kebab-cased CSS variable of the same name — `cardForeground`
+becomes `--card-foreground`, `composerRadius` becomes `--composer-radius`, `scrollbarThumb`
+becomes `--scrollbar-thumb`.
+
+One token breaks that rule:
+
+| Token | CSS variable |
+| --- | --- |
+| `fontFamily` | `--font-agent-ui` |
+
+Alongside the usual surface and text tokens, the palette includes status pairs for
+`destructive`, `success`, and `warning`, each with a matching `*Foreground`.
+
+<Note>
+ `theme.tokens` is a `Partial`, so you only supply the tokens you want to change and the preset
+ fills in the rest. The status pairs matter only if you construct a complete `SemanticTokens`
+ object — for instance when building your own preset — in which case all four of `success`,
+ `successForeground`, `warning`, and `warningForeground` are required.
+</Note>
+
+## Styling rendered content
+
+`theme.classNames` targets the content renderers:
+
+```ts
+type ContentClassNames = {
+ markdown?: string;
+ inlineCode?: string;
+ syntaxHighlighter?: { root?: string; pre?: string; code?: string; lineNumber?: string };
+ openui?: { root?: string; scope?: string };
+ monaco?: { root?: string };
+};
+```
+
+For CSS-only adjustments you can instead target the stable class names directly:
+`.aui-markdown`, `.aui-syntax-highlighter`, `.aui-openui`, `.aui-monaco`.
+
+## Presets
+
+```ts
+import { PRESETS, resolvePresetTokens } from "@truefoundry/trueforge-ui";
+
+const tokens = resolvePresetTokens("gemini", "dark");
+```
+
+`PRESETS` is a `Record<ThemePreset, { light, dark }>` — useful for building a preset picker.
diff --git a/docs/ui-sdk/guides/troubleshooting.mdx b/docs/ui-sdk/guides/troubleshooting.mdx
new file mode 100644
index 000000000..3c245cce3
--- /dev/null
+++ b/docs/ui-sdk/guides/troubleshooting.mdx
@@ -0,0 +1,82 @@
+---
+title: "Troubleshooting"
+description: "Common failure modes and their causes."
+---
+
+<AccordionGroup>
+ <Accordion title="Error: requires an AuiProvider">
+ Two copies of an assistant-ui package are in the bundle. Deduplicate `react`,
+ `react-dom`, `@assistant-ui/core`, `@assistant-ui/react`, and `@assistant-ui/store` — see
+ [Installation](/ui-sdk/get-started/installation).
+ </Accordion>
+
+ <Accordion title="The UI renders but is collapsed to zero height">
+ The SDK fills its parent and sets no height of its own. Give the wrapper a resolved
+ height (`h-dvh` plus `min-h-0`, or an explicit pixel height) and pass
+ `className="h-full min-h-0"`.
+ </Accordion>
+
+ <Accordion title="The SDK renders unstyled">
+ Check that `@import "@truefoundry/trueforge-ui/styles.css";` is actually reaching the
+ browser — that single import is the entire styling setup, and the stylesheet is
+ self-contained. You do not need Tailwind in your own app for the SDK to look right.
+ </Accordion>
+
+ <Accordion title="Your app's own base styles changed after installing">
+ The SDK's stylesheet deliberately omits Tailwind preflight so it cannot reset your styles,
+ so this is unlikely to come from the import itself. Look instead at whether you added
+ `@import "tailwindcss";` at the same time — that one does ship preflight, and it resets
+ host styles by design.
+ </Accordion>
+
+ <Accordion title="An error alert appears immediately on mount">
+ If you passed `type: "trueforge"`, that is expected — the harness adapter has not shipped,
+ so it resolves to a not-implemented error. Use `type: "truefoundry"` or a
+ [custom server](/ui-sdk/guides/custom-server) instead.
+
+ Otherwise the server failed to resolve: check that `apiKey` and `controlPlaneURL` are set
+ and reachable. Attach an `onError` handler to see the underlying error.
+ </Accordion>
+
+ <Accordion title="Requests fail in composer mode with an unknown model">
+ Without an explicit `defaultAgentSpec`, drafts default to `openai-main/gpt-4.1`. Pass a
+ spec naming a model your backend actually exposes:
+ `agentConfig={{ mode: "AgentComposer", defaultAgentSpec: { model: { name: "..." } } }}`.
+ </Accordion>
+
+ <Accordion title="Changing defaultAgentSpec did not affect the open conversation">
+ It seeds a new draft rather than binding to the current one, so the change lands on the next
+ **new chat**. Clear chat will not pick it up — that path preserves the spec already bound to
+ the draft. To apply it to the conversation on screen, remount the component with a new
+ `key`. It is ignored entirely in `SingleAgent` mode.
+ </Accordion>
+
+ <Accordion title="The settings button is missing">
+ Settings render only when your server exposes a `catalog`, so attach one to enable the
+ panel. If you are on a custom layout, that is the other cause — the panel ships with the
+ built-in layouts only.
+ </Accordion>
+
+ <Accordion title="Only the OAuth screen renders — no chat">
+ A `screenType=mcp-auth` query parameter is present on the URL. `TrueforgeUI` renders the
+ OAuth completion screen exclusively in that case. Keep the callback on its own route; see
+ [MCP OAuth](/ui-sdk/guides/mcp-oauth).
+ </Accordion>
+
+ <Accordion title="Dark mode fights with the host application">
+ The provider toggles the `dark` class on `document.documentElement`. Pass a controlled
+ `theme.mode` derived from your own state so the two stay aligned.
+ </Accordion>
+
+ <Accordion title="Import of Button or AskUserPrompt fails">
+ A few names are published as types only, so importing them as values fails. `Button` and
+ `IconButton` are restyled through [theme tokens](/ui-sdk/guides/theming) rather than replaced.
+ `AskUserPrompt`, `McpAuthPrompt`, and `ReasoningCard` are override-only — supply your own
+ component typed with the published props.
+ </Accordion>
+
+ <Accordion title="SSR or React Server Components errors">
+ The package is ESM-only and client-only. Mount `TrueforgeUI` from a client component — in
+ Next.js App Router, a file with `"use client"` at the top.
+ </Accordion>
+</AccordionGroup>
diff --git a/docs/ui-sdk/images/favicon.svg b/docs/ui-sdk/images/favicon.svg
new file mode 100644
index 000000000..f3affb7b2
--- /dev/null
+++ b/docs/ui-sdk/images/favicon.svg
@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32" width="32" height="32">
+ <rect width="32" height="32" rx="7" fill="#0B5FFF"/>
+ <path d="M8 11h16M13 11v13" stroke="#fff" stroke-width="3" stroke-linecap="round"/>
+</svg>
diff --git a/docs/ui-sdk/index.mdx b/docs/ui-sdk/index.mdx
new file mode 100644
index 000000000..e55c3706b
--- /dev/null
+++ b/docs/ui-sdk/index.mdx
@@ -0,0 +1,37 @@
+---
+title: "TrueForge UI SDK"
+description: "A themeable React SDK for building AI agent chat applications."
+---
+
+`@truefoundry/trueforge-ui` gives you a production-ready agent chat experience — streaming
+responses, session history, tool calls with approvals, sub-agents, reasoning traces,
+attachments, and an agent library — as a single React component you can drop into an
+existing app. It is built on [assistant-ui](https://www.assistant-ui.com/) and follows
+shadcn/ui conventions, so branding, layout, and individual components stay under your
+control.
+
+<CardGroup cols={2}>
+ <Card title="Installation" icon="download" href="/ui-sdk/get-started/installation">
+ Install the package, wire up the stylesheet, and satisfy the peer dependencies.
+ </Card>
+ <Card title="Quickstart" icon="rocket" href="/ui-sdk/get-started/quickstart">
+ A working chat UI in about fifteen lines of JSX.
+ </Card>
+ <Card title="Architecture" icon="layer-group" href="/ui-sdk/concepts/architecture">
+ How atoms, containers, layouts, and slots fit together.
+ </Card>
+ <Card title="API reference" icon="code" href="/ui-sdk/reference/trueforge-ui">
+ Every export, prop, and type.
+ </Card>
+</CardGroup>
+
+## What you get
+
+The SDK ships one entry component, `TrueforgeUI`, which mounts its own provider stack and
+renders either one of four built-in layouts or a layout you write. Everything below that is
+prop-driven: pick a server, pick a layout, optionally pass a theme and a set of slot overrides.
+
+Backends are pluggable. Point the SDK at a TrueFoundry control plane, or implement the
+`AgentUIServer` interface yourself and hand the object straight to the component. A third
+option, `type: "trueforge"` for the harness adapter, is typed but not yet implemented. The
+[quickstart](/ui-sdk/get-started/quickstart) covers all three.
diff --git a/docs/ui-sdk/reference/atoms.mdx b/docs/ui-sdk/reference/atoms.mdx
new file mode 100644
index 000000000..923404f4d
--- /dev/null
+++ b/docs/ui-sdk/reference/atoms.mdx
@@ -0,0 +1,115 @@
+---
+title: "Atoms"
+description: "Presentational components and their prop types."
+---
+
+Atoms are pure presentational components. Most publish a matching `*Props` type, and most are
+overridable slots — but neither is universal, so check
+[Slot overrides](/ui-sdk/guides/slot-overrides) for which names `overrides` accepts, and rely on your
+editor for which props types exist.
+
+## Messages and content
+
+| Export | Notable props |
+| --- | --- |
+| `AssistantMessageBubble` | `{ children, error?, actionBar?, className? }` |
+| `UserMessageBubble` | `{ text, attachments?, editAction?, className? }` |
+| `UserMessageEdit` | edit-in-place composer for a sent message |
+| `UserMessageActionBar`, `MessageActionBar` | per-message actions |
+| `MessageErrorBanner`, `MessageIndicator`, `MessageTimestamp` | status affordances |
+| `Markdown` | `{ content, isStreaming?, fileDownloadBaseUrl?, onDownloadArtifact?, readOnly?, className?, inlineCodeClassName? }` |
+| `OpenUiFenceBlock` | renders OpenUI fenced blocks |
+| `SyntaxHighlighter` | highlighted code |
+| `SandboxArtifactDownload`, `ChatFileDownload` | artifact and file download affordances |
+| `WelcomeScreen` | `{ heading?, icon?, className? }` |
+
+`preloadMarkdownOpenUI()` eagerly loads the OpenUI renderer, avoiding a hitch on the first rich
+message. `ThreadContainer` already calls it on mount, so you only need this in a custom layout
+that does not render `ThreadContainer`.
+
+## Composer
+
+| Export | Notable props |
+| --- | --- |
+| `ComposerShell` | `{ input, disabled, canSubmit, isRunning?, attachments?, modelLabel?, modelIcon?, connectorStatusLabel?, onSubmit, onCancel?, onAttach?, className? }` |
+| `ComposerLeftSection`, `ComposerRightSection` | slots flanking the input |
+| `ComposerSendButton` | submit / cancel control |
+| `AttachmentCard` | attachment chip shown in the composer and on sent messages |
+| `AttachmentPickerButton`, `AttachmentPreviewDialog` | attachment UI |
+
+## Thread shell and list
+
+`ThreadRootShell`, `ThreadViewportShell`, `ThreadComposerAreaShell`, `MessageGroup`,
+`ScrollToBottomButton`, `MessageListSkeleton`, `HistoryLoader`, `ThreadListShell`,
+`ThreadListNewButton`, `ThreadListRow` (`{ title, active, onSelect, agentName?, lastMessageAt?, actions?, className? }`
+— `agentName` renders as a sublabel and `lastMessageAt` as a relative timestamp),
+`ThreadListRowSkeleton`, `ThreadListEmptyState`.
+
+## Tools and prompts
+
+`ToolCallCard` carries the widest surface:
+
+```ts
+type ToolCallStatus = "running" | "success" | "error";
+
+type ToolCallCardProps = {
+ toolName: string;
+ icon?: string;
+ iconClassName?: string;
+ iconVariant?: "primary" | "muted";
+ expanded?: boolean;
+ onToggle?: () => void;
+ awaiting?: boolean;
+ awaitingText?: string;
+ status?: ToolCallStatus;
+ exitCode?: number | null;
+ showExpandChevron?: boolean;
+ showResponseLine?: boolean;
+ responseIcon?: ReactNode;
+ approvalSlot?: ReactNode;
+ requestSlot?: ReactNode;
+ responseSlot?: ReactNode;
+ highlightCard?: boolean;
+ mcpServerName?: string;
+ dataTestPrefix?: string;
+ className?: string;
+};
+```
+
+<Warning>
+ `icon` is an icon **name** looked up in the icon registry, not a rendered node — it defaults
+ to `"mcp-server"`. Passing an element renders nothing useful. To supply your own artwork, map
+ the name through `theme.icons`; see [Theming](/ui-sdk/guides/theming).
+</Warning>
+
+Also `ToolCallContentBlock`, `ToolApprovalBar`, `ToolGroupCard`, `SubAgentCard`,
+`SandboxToolCallCard`, `AgentStepsCard`.
+
+<Note>
+ `AskUserPrompt`, `McpAuthPrompt`, and `ReasoningCard` are override-only: supply your own
+ component for the slot, typed with the published props. The types available are
+ `AskUserPromptProps`, `AskUserQuestionCardProps`, `AskUserQuestion`,
+ `AskUserAnsweredQuestion`, `AskUserAnswerDraft`, `McpAuthPromptProps`, `McpAuthCardProps`,
+ `McpAuthServer`, and `ReasoningCardProps`.
+</Note>
+
+## Agent library and draft composer
+
+`AgentsLibrary` (`{ open, onOpenChange, onSelectAgent? }`), `AgentsLibraryButton`,
+`SaveAgentButton`, `ClearChatButton`, `SelectAgentEmptyState`, `DraftCatalogProvider`,
+`useDraftCatalog()`, `DraftComposerLeftSection`, `DraftComposerRightSection`,
+`DraftCompositeSelector`, `DraftModelSelector`.
+
+All of these except `DraftCatalogProvider` and `useDraftCatalog` are also overridable slots, so
+you can either render them yourself or replace them globally through `overrides`.
+
+## Primitives
+
+`BottomSheet`, `CenteredModal`, `Avatar` / `AvatarImage` / `AvatarFallback`, `Icon`, `Toast`,
+`ToastStack`, `CodeEditor`, `MonacoEditorCore`.
+
+<Note>
+ `ButtonProps`, `ButtonVariant`, `ButtonSize`, and `IconButtonProps` are available as types
+ for typing your own components. The buttons themselves are styled through semantic tokens
+ rather than replaced — see [Theming](/ui-sdk/guides/theming).
+</Note>
diff --git a/docs/ui-sdk/reference/catalog.mdx b/docs/ui-sdk/reference/catalog.mdx
new file mode 100644
index 000000000..d71011c70
--- /dev/null
+++ b/docs/ui-sdk/reference/catalog.mdx
@@ -0,0 +1,248 @@
+---
+title: "Settings catalog"
+description: "The optional catalog port behind the model, connector, skill, and sandbox settings."
+---
+
+`catalog` is the optional fourth part of an [`AgentUIServer`](/ui-sdk/concepts/server-contract). Attach
+it and the settings UI appears; omit it and those surfaces stay hidden.
+
+```ts
+interface CatalogServer {
+ modelCatalog: ModelCatalogServer;
+ connectorCatalog: ConnectorCatalogServer;
+ skillCatalog?: SkillCatalogServer;
+ sandboxCatalog?: SandboxCatalogServer;
+}
+```
+
+Models and connectors are required; skills and sandboxes are optional, so omit either when your
+product has no such settings page.
+
+Two conventions recur across all four. Every catalog exposes a **discovery** list of things the
+user could add (`get*Catalog`) alongside a list of what they have already configured
+(`list*`). And public read shapes never carry secrets — `apiKey` is accepted on writes and
+never returned.
+
+<AccordionGroup>
+ <Accordion title="Model providers" defaultOpen>
+ ```ts
+ interface ModelCatalogServer {
+ getModelProviderCatalog(): Promise<ModelProviderCatalogEntry[]>;
+ listModelProviders(): Promise<ModelProviderBase[]>;
+ createModelProvider(req: CreateModelProviderRequest): Promise<ModelProviderBase>;
+ updateModelProvider(req: UpdateModelProviderRequest): Promise<ModelProviderBase>;
+ deleteModelProvider?(req: { id: string }): Promise<void>;
+ }
+ ```
+
+ ```ts
+ interface ModelEntry {
+ id: string; // the model ID sent to the provider
+ name: string; // display name
+ }
+
+ interface ModelProviderBase {
+ id: string;
+ type: ProviderType;
+ name: string;
+ baseUrl?: string;
+ models: ModelEntry[];
+ }
+ ```
+
+ `ProviderType` is a `string`. The literal `"custom"` is reserved for user-defined
+ providers; any other value denotes a builtin such as `"openai"` or `"anthropic"`.
+ `baseUrl` is present exactly when `type` is `"custom"` — builtins resolve their own
+ endpoint.
+
+ Writes carry the key: `CreateModelProviderRequest` is
+ `{ type, name, baseUrl?, apiKey, models }`, and the update form is the same plus a required
+ `id`. Updates are a **full replace** keyed by `id`, not a patch — send the complete
+ `models` array, since omitted entries are dropped.
+
+ `ModelProviderCatalogEntry` is discovery-only —
+ `{ type, name, models, supportedReasoningEfforts?, logo? }` — with no `id` and no key. Its
+ `type` is never `"custom"`, because a custom provider is created through the custom form
+ rather than picked from a catalog.
+
+ `supportedReasoningEfforts` lists the effort levels the provider's models accept, which the
+ custom-provider form offers when configuring a model. `logo` is an optional image for the
+ provider card.
+ </Accordion>
+
+ <Accordion title="Connectors (MCP servers)">
+ ```ts
+ interface ConnectorCatalogServer {
+ getConnectorCatalog(): Promise<ConnectorCatalogEntry[]>;
+ listConnectors(req?: { query?: string }): Promise<ConnectorBase[]>;
+ createConnector(req: CreateConnectorRequest): Promise<ConnectorBase>;
+ updateConnector(req: UpdateConnectorRequest): Promise<ConnectorBase>;
+ authenticateConnector(
+ req: AuthenticateConnectorRequest,
+ ): Promise<ConnectorBase | ConnectorAuthenticationResult>;
+ disconnectConnector(req: { id: string }): Promise<ConnectorBase>;
+ deleteConnector?(req: { id: string }): Promise<void>;
+ }
+ ```
+
+ ```ts
+ interface ConnectorBase {
+ id: string;
+ name: string;
+ description: string;
+ url: string;
+ auth: ConnectorAuthPublic;
+ requiresAuth: boolean;
+ authenticated: boolean;
+ }
+ ```
+
+ `requiresAuth: false` tells the UI to hide the Disconnect action. `authenticated` drives the
+ connected/disconnected state shown to the user.
+
+ Auth comes in two parallel unions — one for writes, one for public reads:
+
+ | `type` | Write (`ConnectorAuth`) | Public (`ConnectorAuthPublic`) |
+ | --- | --- | --- |
+ | `"dcr"` | `{ authUrl?: string }` | `{ authUrl: string }` — required |
+ | `"header"` | `{ apiKey?, headerName? }` | `{ headerName? }` — no key |
+ | `"none"` | `—` | `—` |
+
+ The write union accepts an `apiKey`; the public union has no such field, which is what keeps
+ secrets out of read paths. For `dcr`, `authUrl` is required on the public shape because the
+ UI needs somewhere to send the user.
+
+ `authenticateConnector` starts the OAuth flow. It takes
+ `{ id, redirectURL? }` — `redirectURL` being the callback page your application owns — and
+ its return type is a union:
+
+ ```ts
+ interface ConnectorAuthenticationResult {
+ connector?: ConnectorBase;
+ status?: string;
+ authorization_endpoint?: string;
+ }
+ ```
+
+ Return a plain `ConnectorBase` when the connector is already authenticated or when
+ `auth.authUrl` carries the authorize URL. Return the result object when the popup flow needs
+ an `authorization_endpoint`. Handle both when consuming it.
+
+ `disconnectConnector` clears auth and returns the updated connector, so the UI can re-render
+ from the response. As with providers, `updateConnector` is a full replace keyed by `id`.
+ </Accordion>
+
+ <Accordion title="Skills">
+ ```ts
+ interface SkillCatalogServer {
+ getSkillCatalog(): Promise<SkillCatalogEntry[]>;
+ listSkills(req?: { query?: string }): Promise<SkillBase[]>;
+ createSkill(req: CreateSkillRequest): Promise<SkillBase>;
+ deleteSkill?(req: { id: string }): Promise<void>;
+ }
+ ```
+
+ Skills are backed by a git source. The fields shared by catalog entries and create requests
+ are:
+
+ ```ts
+ interface SkillConfigBase {
+ name: string;
+ description: string;
+ repoURL: string;
+ path: string;
+ ref: string;
+ }
+ ```
+
+ A skill can be created two ways, and the request is a union of the two:
+
+ ```ts
+ type CreateSkillRequest = SelectRegistrySkillRequest | ImportGithubSkillRequest;
+ ```
+
+ Picking one from the catalog sends `SelectRegistrySkillRequest`, which adds a `catalogId`
+ recording the `SkillCatalogEntry` it came from. Importing a repository directly sends
+ `ImportGithubSkillRequest`, which carries only the git fields. The distinction persists into
+ the read shape: a `RegistrySkill` has `catalogId`, a `GithubSkill` does not.
+
+ There is no `updateSkill` — skills are created and deleted rather than edited. Deletion is
+ asymmetric between the two kinds: removing a registry skill returns it to the catalog as
+ selectable again, while removing a GitHub-imported skill is permanent.
+ </Accordion>
+
+ <Accordion title="Sandbox providers">
+ ```ts
+ interface SandboxCatalogServer {
+ getSandboxProviderCatalog(): Promise<SandboxProviderCatalogEntry[]>;
+ listSandboxProviders(req?: { query?: string }): Promise<SandboxProviderBase[]>;
+ createSandboxProvider(req: CreateSandboxProviderRequest): Promise<SandboxProviderBase>;
+ updateSandboxProvider(req: UpdateSandboxProviderRequest): Promise<SandboxProviderBase>;
+ deleteSandboxProvider?(req: { id: string }): Promise<void>;
+ }
+ ```
+
+ The tunable settings are shared across catalog rows, connected rows, creates, and updates:
+
+ ```ts
+ interface SandboxProviderConfig {
+ snapshotName: string;
+ execTimeoutMs: number;
+ autoStopIntervalInMinutes: number;
+ autoArchiveIntervalInMinutes: number;
+ autoDeleteIntervalInMinutes: number;
+ }
+ ```
+
+ The three lifecycle intervals are a progression: a sandbox stops, is later archived, and is
+ eventually deleted. `execTimeoutMs` caps a single execution rather than the sandbox's
+ lifetime.
+
+ `SandboxProviderBase` extends that config with `{ id, name, catalogId, isConnected }`. Note
+ it carries the last-saved config rather than omitting it, so an update form can show current
+ values without a second fetch. `SandboxProviderCatalogEntry` adds `{ id, name, type }`.
+
+ `CreateSandboxProviderRequest` adds `catalogId`, `name`, `type`, and a required `apiKey`.
+ `UpdateSandboxProviderRequest` takes `id` plus the config, with an **optional** `apiKey` —
+ omit it to keep the existing key, send one to rotate. That is the one place a catalog write
+ is not a straight full replace.
+ </Accordion>
+</AccordionGroup>
+
+## Accessing the catalog
+
+```ts
+import { useCatalogServer, useOptionalCatalogServer } from "@truefoundry/trueforge-ui";
+```
+
+`useCatalogServer()` throws when no catalog is attached, so use it only where one is
+guaranteed. `useOptionalCatalogServer()` returns `null` instead — prefer it in components that
+must render either way.
+
+## Widening
+
+Every catalog interface is generic over its row and request types, following the same pattern as
+[the chat and builder ports](/ui-sdk/concepts/server-contract#widening-the-types):
+
+```ts
+interface MyModelEntry extends ModelEntry {
+ contextWindow: number;
+}
+
+const modelCatalog: ModelCatalogServer<MyModelEntry> = {
+ /* ... */
+};
+```
+
+Note that `ConnectorCatalogServer`'s first type parameter is `TTool extends ToolBase`, so a
+host that surfaces per-connector tool metadata widens there.
+
+Auth branches are widened by intersecting a branch and re-forming the union, so you can add
+fields to one variant without loosening the others:
+
+```ts
+type MyConnectorAuth =
+ | (ConnectorAuthOAuth & { scopes: string[] })
+ | ConnectorAuthApiKey
+ | ConnectorAuthNone;
+```
diff --git a/docs/ui-sdk/reference/containers.mdx b/docs/ui-sdk/reference/containers.mdx
new file mode 100644
index 000000000..02a5b37ef
--- /dev/null
+++ b/docs/ui-sdk/reference/containers.mdx
@@ -0,0 +1,62 @@
+---
+title: "Containers"
+description: "Runtime-connected building blocks for custom layouts."
+---
+
+Containers are connected to the chat runtime and take most of their data from context, so they
+need few props. Use them to build a [custom layout](/ui-sdk/guides/layouts).
+
+## Primary
+
+| Export | Props | Purpose |
+| --- | --- | --- |
+| `Thread` | none | Convenience wrapper: `<ThreadContainer composer={<ComposerContainer />} />`. |
+| `ThreadContainer` | `{ composer?: ReactNode }` | The message transcript with an optional composer slot beneath it. |
+| `ComposerContainer` | `{ placeholder?: string }` | Input, attachments, model label, send/cancel. |
+| `ThreadListContainer` | `{ onThreadOpen?: () => void }` | Session list with new-chat affordance. |
+| `TrueFoundryChatProvider` | see below | Mounts the chat runtime. |
+
+```ts
+type TrueFoundryChatProviderProps = {
+ server: AgentUIServer;
+ initialSessionId?: string;
+ adapters?: UseTrueFoundryAgentRuntimeOptions["adapters"];
+ onError?: (error: unknown) => void;
+ children: ReactNode;
+ agent?: TrueFoundryAgentConfig;
+ agentName?: string;
+ listSessionsAgentId?: string;
+};
+```
+
+Use `agent` to select which agent the provider runs; `agentName` is a string-only shorthand kept
+for compatibility. `listSessionsAgentId` is forwarded to `listSessions` to filter the history
+list to a single agent — that is how `TrueforgeUI` scopes the thread list.
+
+## Message and content wiring
+
+`AssistantMessageContainer`, `AssistantTextContainer`, `UserMessageContainer`,
+`UserEditComposerContainer`, `MessageAttachmentsContainer`, `HistoryLoaderContainer`,
+`ReasoningContainer`.
+
+## Tools
+
+`ToolCallContainer`, `ToolCallContentBlockContainer`, `ToolGroupContainer`,
+`ToolApprovalContainer`, `AgentStepsContainer`, `AskUserContainer`.
+
+## Composer attachments
+
+`ComposerAttachmentsContainer`, `ComposerAttachmentPickerContainer`.
+
+## MCP OAuth
+
+`McpAuthContainer`, `PostMcpOauthScreen`.
+
+## Errors
+
+`ErrorToasterProvider`, `useErrorToaster()`, `useErrorToasterOptional()`.
+
+<Note>
+ The settings panel is part of the built-in layouts and has no standalone container. Custom
+ layouts supply their own, built against the `catalog` server.
+</Note>
diff --git a/docs/ui-sdk/reference/events.mdx b/docs/ui-sdk/reference/events.mdx
new file mode 100644
index 000000000..113ae791a
--- /dev/null
+++ b/docs/ui-sdk/reference/events.mdx
@@ -0,0 +1,312 @@
+---
+title: "Streaming events"
+description: "The event protocol createTurn yields and the UI folds into a transcript."
+---
+
+`createTurn` is an async generator. Each value it yields is an envelope, not a bare event:
+
+```ts
+interface TurnStreamData {
+ sequenceNumber: number;
+ event: TurnStreamingEvent;
+}
+```
+
+<Note>
+ `@truefoundry/trueforge-ui` types `TurnStreamingEvent` openly as
+ `{ type: string; [key: string]: unknown }`, so TypeScript will not check the shapes on this
+ page for you — emit an event whose fields do not match and it compiles cleanly, then fails to
+ render. Treat these shapes as required regardless.
+
+ The named event interfaces below are declared in `@truefoundry/assistant-ui-runtime`. Import
+ them from there if you want compile-time checking when building a server.
+</Note>
+
+`sequenceNumber` must increase monotonically within a turn. It is what
+[`subscribeToTurn`](/ui-sdk/concepts/server-contract#agentchatserver) uses to resume — a reconnecting
+client passes the last number it saw as `afterSequenceNumber`, and you replay only what follows.
+
+```ts
+async *createTurn({ sessionId, input }) {
+ let seq = 0;
+ for await (const event of myBackendStream(sessionId, input)) {
+ yield { sequenceNumber: seq++, event };
+ }
+}
+```
+
+## Turn lifecycle
+
+Every turn is bracketed by two lifecycle events.
+
+```ts
+interface TurnCreatedEvent {
+ type: "turn.created";
+ id: string;
+ turnId: string;
+ previousTurnId?: string | null;
+ input?: TurnInputItem[];
+ state?: { status: "running" };
+ createdAt: string;
+ threadId?: string | null;
+}
+
+interface TurnDoneEvent {
+ type: "turn.done";
+ id: string;
+ state: Exclude<TurnState, { status: "running" }>;
+ createdAt: string;
+ threadId?: string | null;
+}
+```
+
+Emit `turn.created` first, then content events, then exactly one `turn.done`. Because
+`turn.done`'s `state` excludes `running`, it must carry a terminal state — `done`, `cancelled`,
+or `error` — each with a `completedAt`. A stream that ends without `turn.done` leaves the UI
+believing the turn is still running.
+
+## Content events
+
+<AccordionGroup>
+ <Accordion title="model.message — a complete assistant message" defaultOpen>
+ ```ts
+ interface ModelMessageEvent {
+ type: "model.message";
+ id: string;
+ threadId: string;
+ content?: string | ModelMessageContentPart[] | null;
+ name?: string;
+ refusal?: string | null;
+ reasoningContent?: string;
+ toolCalls?: ToolCall[];
+ finishReason?: string | null;
+ createdAt: string;
+ usage?: unknown;
+ }
+
+ type ModelMessageContentPart =
+ | { type: "text"; text: string }
+ | { type: "refusal"; refusal: string }
+ | { type: "image_url"; image_url: { url: string } };
+ ```
+
+ `content` is either a plain string or an array of parts when the message mixes text with
+ images or a refusal. `reasoningContent` populates the reasoning card. `toolCalls` carries
+ fully-formed calls — see the tool calls section below.
+ </Accordion>
+
+ <Accordion title="model.message.delta — incremental text">
+ ```ts
+ interface ModelMessageDeltaEvent {
+ type: "model.message.delta";
+ id: string;
+ threadId: string;
+ content?: string | null;
+ refusal?: string | null;
+ reasoningContent?: string;
+ toolCalls?: ChunkDeltaToolCall[];
+ finishReason?: string | null;
+ createdAt?: string;
+ usage?: unknown;
+ contentBlocks?: Array<{
+ index: number;
+ delta:
+ | { type: "text"; text?: string }
+ | { type: "image_url"; image_url?: { url?: string } };
+ }>;
+ content_blocks?: Array<{ index: number; delta: /* same as above */ }>;
+ }
+ ```
+
+ Deltas accumulate against the `id` of the message they belong to, so reuse one `id` across
+ every delta for a given message. `content` on a delta is the *increment*, not the running
+ total.
+
+ `contentBlocks` carries block-level deltas, used for streaming images alongside text, keyed
+ by `index`. Both the camelCase and `snake_case` spellings are accepted; emit
+ `contentBlocks` in new code.
+ </Accordion>
+
+ <Accordion title="tool.response — the result of a tool call">
+ ```ts
+ interface ToolResponseEvent {
+ type: "tool.response";
+ id: string;
+ threadId: string;
+ toolCallId: string;
+ content: string;
+ createdAt: string;
+ }
+ ```
+
+ `toolCallId` must match the `id` of the `ToolCall` this responds to. `content` is a string —
+ serialize structured results yourself.
+ </Accordion>
+</AccordionGroup>
+
+## Tool calls
+
+```ts
+interface ToolCall {
+ id: string;
+ type: "function";
+ function: { name: string; arguments: string };
+ toolInfo?: ToolInfo;
+ providerSpecificFields?: Record<string, unknown>;
+}
+
+type ToolInfo =
+ | { type: "truefoundry-system"; name: string }
+ | { type: "mcp"; serverId: string; serverName: string; name: string }
+ | { type: string; name?: string; [key: string]: unknown };
+```
+
+`function.arguments` is a JSON **string**, not an object. `toolInfo` drives presentation: the
+`mcp` variant is what lets the UI label a call with the server it came from, and the open third
+variant lets you introduce your own tool categories.
+
+Streaming a call in pieces uses a delta shape keyed by position:
+
+```ts
+interface ChunkDeltaToolCall {
+ index: number;
+ id?: string;
+ type?: "function";
+ function?: { name?: string; arguments?: string };
+ toolInfo?: ToolInfo;
+ providerSpecificFields?: Record<string, unknown>;
+}
+```
+
+Every field except `index` is optional, because a call is assembled across several deltas —
+typically `id` and `function.name` first, then `function.arguments` in fragments. Accumulate by
+`index` within the message.
+
+## Pausing for the user
+
+Three events tell the UI a turn cannot proceed unattended:
+
+```ts
+type ActionRequiredEvent =
+ | ToolApprovalRequiredEvent
+ | ToolResponseRequiredEvent
+ | McpAuthRequiredEvent;
+```
+
+```ts
+interface ToolApprovalRequiredEvent {
+ type: "tool.approval_required";
+ id: string;
+ createdAt: string;
+ threadId: string;
+ toolCalls: ToolCallRef[];
+}
+
+interface ToolCallRef {
+ id: string;
+ sourceEventId: string;
+}
+```
+
+`tool.response_required` has the identical shape and asks the user to supply a result rather
+than approve one. A `ToolCallRef` needs both the tool call's `id` and `sourceEventId` — the `id`
+of the event that emitted the call — so the UI can attach the prompt to the right card.
+
+```ts
+interface McpAuthRequiredEvent {
+ type: "mcp.auth_required";
+ id: string;
+ createdAt: string;
+ threadId?: string | null;
+ mcpServers: Array<{ id: string; name: string; authUrl: string }>;
+}
+```
+
+`authUrl` is the URL the popup opens. See [MCP OAuth](/ui-sdk/guides/mcp-oauth).
+
+<Note>
+ These events also appear in `requiredActions` on a `done` turn state. That is how a turn that
+ finished *while waiting* on the user communicates what it needs — a `done` turn carrying
+ `requiredActions` is paused, not complete.
+</Note>
+
+The user's reply comes back through `createTurn` as a `user.tool_approval` or
+`user.tool_response` [input item](/ui-sdk/concepts/server-contract#turn-input), carrying the same
+`toolCallId`.
+
+## Sub-agents
+
+Sub-agents are modelled as separate threads. Nearly every event carries a `threadId`, and the
+UI groups events by it.
+
+```ts
+interface ThreadCreatedEvent {
+ type: "thread.created";
+ id: string;
+ threadId: string;
+ title: string;
+ agentInfo: { type?: string; name: string; input: string; model?: string };
+ parent: { threadId: string; toolCallId: string };
+ createdAt: string;
+}
+
+interface ThreadDoneEvent {
+ type: "thread.done";
+ id: string;
+ threadId: string;
+ title?: string;
+ createdAt: string;
+ state?: unknown;
+}
+```
+
+`parent` is what nests a sub-agent under the tool call that spawned it: the parent thread's
+`threadId` plus the `toolCallId`. `agentInfo` populates the sub-agent card — `name`, the `input`
+it was given, and optionally the `model` it runs.
+
+## Sandboxes and MCP setup
+
+```ts
+interface SandboxCreatedEvent {
+ type: "sandbox.created";
+ id: string;
+ createdAt: string;
+ sandboxId: string;
+ threadId: string | null;
+}
+```
+
+`sandboxId` is what you pass to
+[`downloadSandboxFile`](/ui-sdk/concepts/server-contract#agentchatserver) to retrieve artifacts the
+agent produced.
+
+`mcp.initialize` (`{ type, id, createdAt, threadId }`, plus any additional fields you attach)
+reports MCP server startup.
+
+## The unions
+
+| Union | Contains | Where it appears |
+| --- | --- | --- |
+| `TurnEvent` | `model.message`, `tool.response`, `thread.created`, `thread.done`, `mcp.auth_required`, `mcp.initialize`, `sandbox.created`, `tool.approval_required`, `tool.response_required` | `listTurnEvents` |
+| `TurnStreamingEvent` | `TurnEvent` plus `model.message.delta`, `turn.created`, `turn.done` | `createTurn`, `subscribeToTurn` |
+| `ActionRequiredEvent` | the three pause events | `TurnState.requiredActions` |
+
+The distinction is that `TurnEvent` holds the settled record of a turn, while
+`TurnStreamingEvent` adds the transient deltas and lifecycle markers that only matter live.
+This is why replaying a turn from history yields no deltas — the assembled `model.message` is
+stored instead.
+
+`listEvents` returns a session-level wrapper that identifies the turn rather than a position:
+
+```ts
+interface SessionEventItem {
+ turnId: string;
+ event: TurnCreatedEvent | TurnDoneEvent | TurnEvent;
+}
+```
+
+<Warning>
+ Note the asymmetry between the two envelopes: `createTurn` yields
+ `{ sequenceNumber, event }`, while `listEvents` returns `{ turnId, event }`. Streaming is
+ ordered within one turn; history spans many, so it labels each event with its turn instead.
+</Warning>
diff --git a/docs/ui-sdk/reference/hooks.mdx b/docs/ui-sdk/reference/hooks.mdx
new file mode 100644
index 000000000..748bb25a2
--- /dev/null
+++ b/docs/ui-sdk/reference/hooks.mdx
@@ -0,0 +1,64 @@
+---
+title: "Hooks"
+description: "Composer state, MCP auth, runtime hooks, and re-exports."
+---
+
+## Composer state
+
+| Hook | Returns |
+| --- | --- |
+| `useComposerBusyState()` | Whether the composer is busy. Requires `ComposerBusyProvider`. Type: `ComposerBusyState`. |
+| `useComposerPauseView()` | `{ kind: "mcp" \| "ask-user" \| "compose" }` — why input is paused. Types: `ComposerPauseView`, `ThreadPauseState`. |
+
+`threadHasPendingMcpAuth(state)` is the standalone predicate behind the `"mcp"` case.
+
+## MCP auth
+
+```ts
+const auth = useMCPAuth({ callbackPath: "/mcp-callback" });
+```
+
+`MCP_AUTH_POPUP_CHANNEL` is `"truefoundry-mcp-auth-popup"` — the `BroadcastChannel` name used
+to signal completion back to the opener. Types: `McpAuthCallback`, `McpAuthPopupMessage`,
+`UseMCPAuthOptions`. See [MCP OAuth](/ui-sdk/guides/mcp-oauth).
+
+## assistant-ui state
+
+`useAui`, `useAuiState`, and the `AssistantState` type come from `@assistant-ui/react`, which
+the SDK bundles as a dependency and also declares as an optional peer. They are re-exported from
+the package root and from a dedicated subpath:
+
+```ts
+import { useAui, useAuiState } from "@truefoundry/trueforge-ui/assistant-ui";
+```
+
+## Runtime hooks
+
+Import these from `@truefoundry/trueforge-ui` like everything else:
+
+| Export | Purpose |
+| --- | --- |
+| `useTrueFoundryAgentRuntime` | The underlying runtime hook. |
+| `useTrueFoundryAgentSpec` | Read the active agent spec. |
+| `useTrueFoundryUpdateAgentSpec` | Mutate the draft spec. |
+| `useTrueFoundryCancel` | Cancel the in-flight turn. |
+| `useTrueFoundryTurnId` | The id of the current turn. |
+| `useTrueFoundryHistoryPagination` | Page backwards through history. |
+| `useTrueFoundryMcpAuth` | Low-level MCP auth state. |
+| `useTrueFoundryRespondToToolApproval` | Approve or reject a tool call. |
+| `useTrueFoundryToolResponses` | Read tool responses. |
+| `useTrueFoundryDownloadSandboxFile` | Download a sandbox artifact. |
+| `mergeAgentSpec` | Merge partial specs. |
+| `trueFoundryAttachmentAdapter` | Default attachment adapter. |
+
+Types: `DraftAgentConfig`, `NamedAgentConfig`, `TrueFoundryAgentConfig`,
+`UseTrueFoundryAgentRuntimeOptions`.
+
+## Utilities
+
+```ts
+computeAgentStepsSplit(parts: AgentStepPart[], isRunning: boolean): AgentStepsSplitResult;
+```
+
+Splits message parts into the steps shown inline versus those collapsed into the steps card.
+Both `AgentStepPart` and `AgentStepsSplitResult` are exported.
diff --git a/docs/ui-sdk/reference/server.mdx b/docs/ui-sdk/reference/server.mdx
new file mode 100644
index 000000000..82a3bb68b
--- /dev/null
+++ b/docs/ui-sdk/reference/server.mdx
@@ -0,0 +1,84 @@
+---
+title: "Server"
+description: "Server factory, context hooks, shell mode, and contract types."
+---
+
+## Factory
+
+```ts
+createTrueFoundryServer(options: CreateTrueFoundryServerOptions): TrueFoundryServer;
+```
+
+Options: `{ chatServer, getModels, getSkills, getMcp, searchAgents, saveAgent, deleteAgent?, catalog? }`.
+Combines a chat server with your agent-management callbacks into a complete `AgentUIServer`.
+If you omit `deleteAgent`, calling it throws — supply one to support agent deletion.
+
+## Context
+
+| Export | Behavior |
+| --- | --- |
+| `ServerProvider` | Supplies the resolved server. |
+| `useServer()` | The server; throws outside a provider. |
+| `useOptionalServer()` | The server, or `null` outside a provider. |
+| `useCatalogServer()` | `server.catalog`; **throws** when absent. |
+| `useOptionalCatalogServer()` | `server.catalog`, or `null` when there is none. |
+
+## Shell mode
+
+| Export | Behavior |
+| --- | --- |
+| `ShellModeProvider` | Derives shell capabilities from `agentConfig`. |
+| `useShellMode()` | Throws outside a provider. |
+| `useOptionalShellMode()` | Returns `null` outside a provider. |
+| `DEFAULT_AGENT_CONFIG` | `{ mode: "AgentLibraryWithComposer" }`. |
+
+`useShellMode()` reports which surfaces the current `agentConfig` permits —
+`isLibraryEnabled`, `isComposerEnabled`, `isNewChatEnabled` — and returns the actions
+`selectAgent`, `openDraft`, and `clearChat`, plus `settingsOpen` / `setSettingsOpen`. Use it in
+a custom layout to render only the controls that apply. See
+[Agent modes](/ui-sdk/concepts/agent-modes).
+
+## Contract types
+
+The full server contract is re-exported from the package root. The types you are most likely
+to reference:
+
+<AccordionGroup>
+ <Accordion title="Server interfaces">
+ `AgentUIServer`, `AgentChatServer`, `AgentBuilderServer`, `CatalogServer`,
+ `TrueforgeServerConfig`, `CreateTrueFoundryServerOptions`, `TrueFoundryServer`.
+ </Accordion>
+ <Accordion title="Sessions and turns">
+ `Session`, `CreateSessionRequest`, `UpdateSessionRequest`, `Turn`, `TurnState`,
+ `PreviousTurnIdInput`.
+ </Accordion>
+ <Accordion title="Turn input">
+ `TurnInputItem`, `UserMessage`, `UserMessageContent`, `UserToolApprovalEvent`,
+ `UserToolResponseEvent`, `ApprovalDecision`.
+ </Accordion>
+ <Accordion title="Events and streaming">
+ `TurnStreamData`, `TurnStreamingEvent`, `SessionEvent`, `SessionEventItem`. These are typed
+ openly as `{ type: string; [key: string]: unknown }`; the concrete shapes are in
+ [Streaming events](/ui-sdk/reference/events).
+ </Accordion>
+ <Accordion title="Agents and models">
+ `AgentSpec`, `AgentConfig`, `ShellMode`, `Model`, `ModelParams`, `SkillMount`,
+ `McpServerMount`, `SaveAgentRequest`.
+ </Accordion>
+ <Accordion title="Picker rows">
+ `ModelSelection`, `AgentSkill`, `ConnectorState`, `AgentLibraryEntry`,
+ `SearchAgentsParams`.
+ </Accordion>
+ <Accordion title="Pagination">
+ `PageResult`, `PageParams`, `TokenPagination`, `ListSessionsParams`, `ListSessionsOrder`,
+ `ListSessionsResponse`, `ListTurnsResponse`, `ListSessionEventsResponse`.
+ </Accordion>
+ <Accordion title="Catalog">
+ `ModelCatalogServer`, `ConnectorCatalogServer`, `SkillCatalogServer`,
+ `SandboxCatalogServer`, plus the `ModelProvider*`, `Connector*`, `Skill*`, and `Sandbox*`
+ families. See [Settings catalog](/ui-sdk/reference/catalog).
+ </Accordion>
+</AccordionGroup>
+
+Full method signatures are on [Server contract](/ui-sdk/concepts/server-contract); a worked
+implementation is on [Bring your own server](/ui-sdk/guides/custom-server).
diff --git a/docs/ui-sdk/reference/theme.mdx b/docs/ui-sdk/reference/theme.mdx
new file mode 100644
index 000000000..c6770e9ee
--- /dev/null
+++ b/docs/ui-sdk/reference/theme.mdx
@@ -0,0 +1,53 @@
+---
+title: "Theme"
+description: "Theme provider, hooks, presets, brand, and slots."
+---
+
+## Components
+
+| Export | Purpose |
+| --- | --- |
+| `ThemeProvider` | Owns light/dark/system state and injects token CSS variables on a wrapper `div.aui-theme-root`. |
+| `SlotsProvider` | Slot override registry. Must sit outside `TrueFoundryChatProvider`. |
+| `BrandLogo` | Renders `theme.brand.logo`; falls back to a default mark plus brand name. Props: `{ className? }`. |
+| `BrandIcon` | Renders `theme.brand.icon`, falling back to the bare default mark — no name. Props: `{ className? }`. |
+| `Icon` | Renders a built-in icon by name, or your replacement when `theme.icons` maps that name. Props: `{ name: string \| readonly string[] } & IconProps`. An array resolves to its **last** element, accommodating Font Awesome-style `["far", "clone"]` tuples; it is not a fallback chain. An unresolved name renders nothing. |
+
+## Hooks
+
+| Hook | Returns |
+| --- | --- |
+| `useTheme()` | `{ preset, mode, preference, isDark, setTheme }`. `setTheme` is a no-op when `theme.mode` is controlled. |
+| `useThemeMode()` | Resolved `"light" \| "dark"`. Reads the mode published by `SlotsProvider`, so it returns `"light"` when no `SlotsProvider` is above it — even in dark mode. |
+| `useBrand()` | The active `BrandConfig`. |
+| `useThemeIcons()` | The `IconMap` from `theme.icons`. |
+| `useContentClassNames()` | `theme.classNames`; throws outside a provider. |
+| `useOptionalContentClassNames()` | Same, but returns `{}` outside a provider instead of throwing — no null check needed. |
+| `useSlot(name)` | The component currently registered for a slot. |
+
+## Values
+
+| Export | Description |
+| --- | --- |
+| `PRESETS` | `Record<ThemePreset, { light, dark }>` token maps — useful for building a preset picker. |
+| `resolvePresetTokens(preset, mode)` | Resolved tokens for one preset and mode. |
+| `defaultSlots` | The default component for every slot; read it to inspect what a slot renders by default. |
+
+## Types
+
+`ThemeConfig`, `ThemeMode`, `ThemePreset`, `SemanticTokens`, `BrandConfig`, `BrandImage`,
+`ContentClassNames`, `IconMap`, `ThemeIconProps`, `IconProps`, `LayoutProp`, `AtomSlots`,
+`SlotOverrides`.
+
+```ts
+type ThemePreset = "truefoundry" | "claude" | "chatgpt" | "gemini";
+type ThemeMode = "light" | "dark" | "system";
+type SlotOverrides = Partial<AtomSlots>;
+```
+
+`AtomSlots` is derived from the SDK's default slot table, so it enumerates exactly the
+overridable slots — your editor's autocomplete on `overrides` is authoritative. See
+[Slot overrides](/ui-sdk/guides/slot-overrides).
+
+Most token names map to a CSS variable of the same name; the exceptions are listed in
+[Theming](/ui-sdk/guides/theming).
diff --git a/docs/ui-sdk/reference/trueforge-ui.mdx b/docs/ui-sdk/reference/trueforge-ui.mdx
new file mode 100644
index 000000000..e9752e7e6
--- /dev/null
+++ b/docs/ui-sdk/reference/trueforge-ui.mdx
@@ -0,0 +1,202 @@
+---
+title: "TrueforgeUI"
+description: "The entry component and every prop it accepts."
+---
+
+```tsx
+import { TrueforgeUI } from "@truefoundry/trueforge-ui";
+```
+
+## Properties
+
+<ParamField path="server" type="TrueforgeServerConfig" required>
+ Where the chat gets its data. Either a built-in config object or a ready `AgentUIServer`.
+
+ <Expandable title="TrueforgeServerConfig">
+ <ParamField path="type" type='"truefoundry" | "trueforge"'>
+ Omit entirely to pass an `AgentUIServer` object directly — there is no `"custom"` wrapper.
+ `"trueforge"` is typed for the forthcoming harness adapter and currently resolves to a
+ not-implemented error.
+ </ParamField>
+ <ParamField path="apiKey" type="string" required>
+ Required by both built-in types. Client-side keys are for local development only.
+ </ParamField>
+ <ParamField path="controlPlaneURL" type="string" required>
+ TrueFoundry control plane URL. Required when `type` is `"truefoundry"`.
+ </ParamField>
+ <ParamField path="gatewayPlaneURL" type="string">
+ Target a specific gateway. Resolved from the control plane when omitted.
+ </ParamField>
+ <ParamField path="catalog" type="CatalogServer">
+ Attach to enable the settings panel. See [Settings catalog](/ui-sdk/reference/catalog).
+ </ParamField>
+ </Expandable>
+
+ See [Server contract](/ui-sdk/concepts/server-contract).
+</ParamField>
+
+<ParamField path="layout" type="LayoutProp" required>
+ A built-in layout name or your own component.
+
+ <Expandable title="LayoutProp">
+ <ParamField path='"sidebar"' type="BuiltInLayout">
+ Full-page chat with a persistent thread list.
+ </ParamField>
+ <ParamField path='"drawer"' type="BuiltInLayout">
+ Thread list collapses into an overlay drawer.
+ </ParamField>
+ <ParamField path='"dock"' type="BuiltInLayout">
+ Right-pinned panel, capped at 400px. Stacks list and thread.
+ </ParamField>
+ <ParamField path='"widget"' type="BuiltInLayout">
+ Floating launcher expanding into a compact panel.
+ </ParamField>
+ <ParamField path="Custom" type="ComponentType<{ className?: string }>">
+ Your own component, rendered inside the full provider stack.
+ </ParamField>
+ </Expandable>
+
+ See [Layouts](/ui-sdk/guides/layouts).
+</ParamField>
+
+<ParamField path="agentConfig" type="AgentConfig" default='{ mode: "AgentLibraryWithComposer" }'>
+ Which agent-selection surfaces the shell exposes.
+
+ <Expandable title="AgentConfig">
+ <ParamField path='{ mode: "SingleAgent"; name: string }' type="variant">
+ Pins the UI to one named agent. `name` is required; selection controls are hidden.
+ </ParamField>
+ <ParamField path='{ mode: "AgentLibrary" }' type="variant">
+ Users pick from saved agents. New chat is disabled in this mode only.
+ </ParamField>
+ <ParamField path='{ mode: "AgentComposer"; defaultAgentSpec?: AgentSpec }' type="variant">
+ Users assemble an ad-hoc agent.
+ </ParamField>
+ <ParamField path='{ mode: "AgentLibraryWithComposer"; defaultAgentSpec?: AgentSpec }' type="variant">
+ Both surfaces. The default.
+ </ParamField>
+ </Expandable>
+
+ `defaultAgentSpec` seeds a new draft and is picked up on new chat, not on clear chat. See
+ [Agent modes](/ui-sdk/concepts/agent-modes).
+</ParamField>
+
+<ParamField path="theme" type="ThemeConfig">
+ Preset, color mode, tokens, branding, and content class names.
+
+ <Expandable title="ThemeConfig">
+ <ParamField path="preset" type='"truefoundry" | "claude" | "chatgpt" | "gemini"' default='"truefoundry"'>
+ Base token palette.
+ </ParamField>
+ <ParamField path="mode" type='"light" | "dark" | "system"'>
+ Omit for uncontrolled — the SDK resolves `system` and persists the user's choice to
+ `localStorage` under `aui-theme-preference`. Passing a value makes it controlled and turns
+ `setTheme` into a no-op.
+ </ParamField>
+ <ParamField path="tokens" type="Partial<SemanticTokens>">
+ Per-token overrides, merged over the preset and applied as inline styles.
+
+ <Expandable title="SemanticTokens">
+ <ParamField path="Surfaces" type="string">
+ `background`, `foreground`, `card`, `cardForeground`, `popover`, `popoverForeground`.
+ </ParamField>
+ <ParamField path="Palette" type="string">
+ `primary`, `secondary`, `muted`, `accent`, each with a `*Foreground` pair.
+ </ParamField>
+ <ParamField path="Status" type="string">
+ `destructive`, `success`, `warning`, each with a `*Foreground` pair.
+ </ParamField>
+ <ParamField path="Chrome" type="string">
+ `border`, `input`, `ring`, `radius`, `fontFamily` (maps to `--font-agent-ui`).
+ </ParamField>
+ <ParamField path="Optional" type="string">
+ `composerRadius`, `userBubble`, `userBubbleForeground`, `assistantBubble`,
+ `assistantBubbleForeground`, `scrollbarThumb`.
+ </ParamField>
+ </Expandable>
+ </ParamField>
+ <ParamField path="brand" type="BrandConfig">
+ <Expandable title="BrandConfig">
+ <ParamField path="logo" type="BrandImage">
+ Falls back to the default mark plus the brand name.
+ </ParamField>
+ <ParamField path="icon" type="BrandImage">
+ Falls back to the bare mark — no name.
+ </ParamField>
+ <ParamField path="name" type="string" default='"TrueFoundry"'>
+ Shown beside the default logo.
+ </ParamField>
+ </Expandable>
+
+ `BrandImage` accepts `{ src, alt? }`, a React node, or a render function.
+ </ParamField>
+ <ParamField path="icons" type="IconMap">
+ Replace registry icons by name. Values are Lucide components, React nodes, render
+ functions, or SVGR components.
+ </ParamField>
+ <ParamField path="classNames" type="ContentClassNames">
+ <Expandable title="ContentClassNames">
+ <ParamField path="markdown" type="string" />
+ <ParamField path="inlineCode" type="string" />
+ <ParamField path="syntaxHighlighter" type="{ root?, pre?, code?, lineNumber? }" />
+ <ParamField path="openui" type="{ root?, scope? }" />
+ <ParamField path="monaco" type="{ root? }" />
+ </Expandable>
+ </ParamField>
+ <ParamField path="className" type="string">
+ Applied to the theme root wrapper.
+ </ParamField>
+ </Expandable>
+
+ See [Theming](/ui-sdk/guides/theming).
+</ParamField>
+
+<ParamField path="overrides" type="SlotOverrides">
+ Replace any built-in component. `Partial<AtomSlots>`, derived from the SDK's default slot
+ table — so editor autocomplete lists exactly the 59 overridable names. See
+ [Slot overrides](/ui-sdk/guides/slot-overrides).
+</ParamField>
+
+<ParamField path="className" type="string">
+ Passed to the layout component, and to the loading and error states. Typically
+ `"h-full min-h-0"`. To style the theme wrapper instead, use `theme.className`.
+</ParamField>
+
+<ParamField path="initialSessionId" type="string">
+ Open an existing session on mount instead of starting fresh.
+</ParamField>
+
+<ParamField path="adapters" type="RuntimeAdapters">
+ Runtime adapter overrides. Attachments default to `trueFoundryAttachmentAdapter`.
+</ParamField>
+
+<ParamField path="onError" type="(error: unknown) => void">
+ Called when the server fails to resolve or the runtime raises an error.
+</ParamField>
+
+## Behavior notes
+
+The component mounts every provider it needs, so you do not have to wrap it in anything.
+
+Switching agents, starting a new draft, or clearing the chat resets the conversation — the
+current transcript is cleared so that one agent's messages do not carry into another's context.
+Persisted sessions remain available through the thread list.
+
+<Warning>
+ If `window.location.search` contains `screenType=mcp-auth`, the component renders only the
+ OAuth completion screen and no layout. See [MCP OAuth](/ui-sdk/guides/mcp-oauth).
+</Warning>
+
+## Example
+
+```tsx
+<TrueforgeUI
+ server={{ type: "truefoundry", apiKey, controlPlaneURL }}
+ layout="sidebar"
+ agentConfig={{ mode: "AgentComposer", defaultAgentSpec: { model: { name: "openai-main/gpt-4.1" } } }}
+ theme={{ preset: "claude", brand: { name: "Acme" } }}
+ overrides={{ ClearChatButton: MyClearButton }}
+ className="h-full min-h-0"
+ onError={(e) => reportError(e)}
+/>
+```