Skip to content

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

Cleanup references to older package names and update Readme (#250)

Chirag Jain43845f174f66
diff --git a/.gitignore b/.gitignore
index 54635d570..58eaa1060 100644
--- a/.gitignore
+++ b/.gitignore
@@ -3,7 +3,6 @@ dist/
*.tgz
.DS_Store
*.log
-.env
coverage/
.turbo/
*.tsbuildinfo
@@ -18,3 +17,21 @@ data/
# Helm subchart deps are fetched via `helm dependency build` (pinned by the
# committed Chart.lock); the downloaded .tgz/dirs are not committed.
charts/*/charts/
+
+# Secrets / local env (keep committed examples and the unit-test env fixture)
+.env
+.env.*
+!.env.example
+!.env.test
+*.pem
+*.key
+*.p12
+*.pfx
+*.jks
+credentials.json
+service-account*.json
+.aws/
+
+# Local Cursor scratch (committed rules under .cursor/rules/ stay tracked)
+.cursor/notes/
+.cursor/plans/
diff --git a/README.md b/README.md
index 1b418f600..0d8b287c0 100644
--- a/README.md
+++ b/README.md
@@ -1,28 +1,50 @@
-# TrueForge
-
-**The open-source agent harness — the runtime layer that turns an LLM into a working agent.**
+<p align="center">
+ <a href="https://trueforge.dev">
+ <picture>
+ <source srcset="./docs/assets/trueforge-black.svg" media="(prefers-color-scheme: dark)">
+ <source srcset="./docs/assets/trueforge-white.svg" media="(prefers-color-scheme: light)">
+ <img src="./docs/assets/trueforge-black.svg" alt="TrueForge logo">
+ </picture>
+ </a>
+</p>
+<p align="center">The open-source agent harness - the runtime layer that turns an LLM into a working agent</p>
+
+<p align="center">
+ <a href="https://github.com/truefoundry/trueforge/blob/main/LICENSE">
+ <img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT">
+ </a>
+ <a href="https://nodejs.org">
+ <img src="https://img.shields.io/badge/Node.js-%3E%3D22.13-green.svg" alt="Node.js >= 22.13">
+ </a>
+ <a href="https://trueforge.dev">
+ <img src="https://img.shields.io/badge/Documentation-trueforge.dev-blue.svg" alt="Documentation">
+ </a>
+ <a href="https://trueforge.dev/quickstart">
+ <img src="https://img.shields.io/badge/Quickstart-trueforge.dev/quickstart-blue.svg" alt="Quickstart">
+ </a>
+ <a href="https://trueforge.dev/api/overview">
+ <img src="https://img.shields.io/badge/SDK-trueforge.dev/api/overview-blue.svg" alt="SDK">
+ </a>
+</p>
-TrueForge runs the agent execution loop for you — model calls, MCP tools, skills, sandboxing, approvals, context management, and session state — and exposes it three ways: a **chat UI**, an **HTTP API** with a TypeScript **SDK**, and an embeddable **UI SDK**.
-
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
-[![Node.js >= 22.13](https://img.shields.io/badge/Node.js-%3E%3D22.13-green.svg)](https://nodejs.org)
+# TrueForge
-[Documentation](https://trueforge.dev) · [Quickstart](https://trueforge.dev/quickstart) · [SDK](https://trueforge.dev/api/overview) · [API Reference](https://trueforge.dev/api-reference) · [UI SDK](https://trueforge.dev/ui-sdk)
+TrueForge runs the agent execution loop for you - model calls, MCP tools, skills, sandboxing, approvals, context management, and session state - and exposes it three ways: a **chat UI**, an **HTTP API** with a TypeScript **SDK**, and an embeddable **UI SDK**.
![TrueForge Chat UI](./docs/images/hero.png)
## Why TrueForge?
-Building an agent is easy. Running one well is not — you need streaming, session persistence, tool servers, sandboxing, approvals, and a UI. TrueForge gives you that out of the box:
+Building an agent is easy. Running one well is not - you need streaming, session persistence, tool servers, sandboxing, approvals, and a UI. TrueForge gives you that out of the box:
-- **Initial setup from catalogs** — configure [models](https://trueforge.dev/models), [MCP servers](https://trueforge.dev/mcp-servers), [skills](https://trueforge.dev/skills), and a [sandbox](https://trueforge.dev/sandbox) once; agents pick from what you connected. Presets come from shipped YAML catalogs you can customize.
-- **Any model provider** — OpenAI, Anthropic, Google Gemini, and other catalog providers, or any OpenAI-compatible endpoint.
-- **MCP tools** — remote MCP servers with header auth or OAuth, including in-chat authorization.
-- **Skills** — git-backed `SKILL.md` instruction packs, loaded on demand in the sandbox.
-- **Sandbox as a tool** — isolated code/file execution (Daytona today; more providers planned), provisioned only when needed. Secrets stay in the harness.
-- **Human checkpoints** — tool approval, ask-user-questions, and Generative UI in chat.
-- **Context engineering** — subagents, deferred tool loading, Code Mode, large-result offloading, and compaction.
-- **Chat UI + SDK** — use the bundled UI, automate with `@truefoundry/trueforge-sdk`, or embed `@truefoundry/trueforge-ui`.
+- **Initial setup from catalogs** - configure [models](https://trueforge.dev/models), [MCP servers](https://trueforge.dev/mcp-servers), [skills](https://trueforge.dev/skills), and a [sandbox](https://trueforge.dev/sandbox) once; agents pick from what you connected. Presets come from shipped YAML catalogs you can customize.
+- **Any model provider** - OpenAI, Anthropic, Google Gemini, and other catalog providers, or any OpenAI-compatible endpoint.
+- **MCP tools** - remote MCP servers with header auth or OAuth, including in-chat authorization.
+- **Skills** - git-backed `SKILL.md` instruction packs, loaded on demand in the sandbox.
+- **Sandbox as a tool** - isolated code/file execution (Daytona today; more providers planned), provisioned only when needed. Secrets stay in the harness.
+- **Human checkpoints** - tool approval, ask-user-questions, and Generative UI in chat.
+- **Context engineering** - subagents, deferred tool loading, Code Mode, large-result offloading, and compaction.
+- **Chat UI + SDK** - use the bundled UI, automate with `@truefoundry/trueforge-sdk`, or embed `@truefoundry/trueforge-ui`.
It scales down and up: **local mode** (one process, SQLite) or **hosted mode** (Postgres + Redis, Docker Compose or Helm).
@@ -30,7 +52,7 @@ It scales down and up: **local mode** (one process, SQLite) or **hosted mode** (
### Local mode (npx)
-Requires [Node.js](https://nodejs.org) 22.13 or newer. One command, no other infrastructure — UI and backend run locally; data is stored in SQLite:
+Requires [Node.js](https://nodejs.org) 22.13 or newer. One command, no other infrastructure - UI and backend run locally; data is stored in SQLite:
```bash
npx @truefoundry/trueforge
@@ -40,7 +62,7 @@ Then open [http://localhost:8790](http://localhost:8790).
### From source (pnpm)
-Standalone (SQLite) topology from a clone — no Docker. Requires Node.js 22.13+ and [pnpm](https://pnpm.io):
+Standalone (SQLite) topology from a clone - no Docker. Requires Node.js 22.13+ and [pnpm](https://pnpm.io):
```bash
git clone https://github.com/truefoundry/trueforge.git
@@ -49,7 +71,7 @@ cp packages/server/.env.example packages/server/.env
pnpm standalone:dev
```
-Then open [http://localhost:3000](http://localhost:3000) — Vite serves the UI with live reload and proxies API calls to the server on port 8790. See [CONTRIBUTING.md](CONTRIBUTING.md) for the full development guide (including Postgres + Redis).
+Then open [http://localhost:3000](http://localhost:3000) - Vite serves the UI with live reload and proxies API calls to the server on port 8790. See [CONTRIBUTING.md](CONTRIBUTING.md) for the full development guide (including Postgres + Redis).
### Hosted mode (Docker Compose)
@@ -76,8 +98,7 @@ Every environment variable is documented in [`packages/server/.env.example`](pac
The [`charts/trueforge`](charts/trueforge) Helm chart deploys hosted mode with bundled Postgres and Redis (or your own):
```bash
-# TODO: replace <HELM_REPO> with the published Helm repo URL
-helm install trueforge oci://<HELM_REPO>/trueforge \
+helm install trueforge oci://tfy.jfrog.io/tfy-helm/trueforge \
--version <x.y.z>
```
@@ -87,23 +108,23 @@ See the [chart README](charts/trueforge/README.md) (including [`configs.oidc`](c
Full walkthrough: [Quickstart](https://trueforge.dev/quickstart).
-1. **Setup models** — **Settings → Models**, pick a catalog provider, paste your API key.
+1. **Setup models** - **Settings → Models**, pick a catalog provider, paste your API key.
![Configure a model provider](./docs/images/quickstart-models.png)
-2. **Setup connectors & skills** (optional) — **Settings → Connectors** / **Skills**. Skills need a sandbox.
+2. **Setup connectors & skills** (optional) - **Settings → Connectors** / **Skills**. Skills need a sandbox.
![Connectors](./docs/images/quickstart-connectors.png)
-3. **Setup sandbox** (optional) — **Settings → Sandbox providers**. Daytona is the only provider supported today.
+3. **Setup sandbox** (optional) - **Settings → Sandbox providers**. Daytona is the only provider supported today.
![Sandbox](./docs/images/quickstart-sandbox.png)
-4. **Create an agent** — pick a model, attach connectors/skills, write instructions, then **Save as agent**.
+4. **Create an agent** - pick a model, attach connectors/skills, write instructions, then **Save as agent**.
![Save as agent](./docs/images/quickstart-save-agent.png)
-5. **Find it in the Agent Library** — open **Agents Library**, then **Try** or **Edit**. In hosted mode with login enabled, agents created by anyone are visible to everyone — see [Agent Library](https://trueforge.dev/agent-library).
+5. **Find it in the Agent Library** - open **Agents Library**, then **Try** or **Edit**. In hosted mode with login enabled, agents created by anyone are visible to everyone - see [Agent Library](https://trueforge.dev/agent-library).
![Agents Library](./docs/images/quickstart-agents-library.png)
@@ -144,7 +165,7 @@ flowchart LR
| -------------------------------------------------------------- | ----------------------------------------------------------------- |
| [Introduction](https://trueforge.dev/introduction) | What an agent harness is and how TrueForge fits together |
| [Quickstart](https://trueforge.dev/quickstart) | Run local or hosted, build your first agent |
-| [Initial Setup](https://trueforge.dev/harness/initial-setup) | Models, MCP, skills, sandbox — catalogs and overrides |
+| [Initial Setup](https://trueforge.dev/harness/initial-setup) | Models, MCP, skills, sandbox - catalogs and overrides |
| [Create an Agent](https://trueforge.dev/create-agent/overview) | Select resources; tool approval, questions, Generative UI |
| [Key Features](https://trueforge.dev/key-features/overview) | Sandbox-as-tool, subagents, deferred tools, Code Mode, compaction |
| [Benchmarking](https://trueforge.dev/benchmarking) | Cost/accuracy vs Claude Managed Agents and deepagents |
@@ -155,11 +176,11 @@ flowchart LR
## Benchmarks
-We compare TrueForge against Claude Managed Agents and deepagents on the same tasks, tools, and model — same accuracy, lower cost. Reproduce it from [`benchmark/`](benchmark/). Write-up: [Benchmarking](https://trueforge.dev/benchmarking).
+We compare TrueForge against Claude Managed Agents and deepagents on the same tasks, tools, and model - same accuracy, lower cost. Reproduce it from [`benchmark/`](benchmark/). Write-up: [Benchmarking](https://trueforge.dev/benchmarking).
## Contributing
-We love contributions — bug reports, features, and docs fixes. See [CONTRIBUTING.md](CONTRIBUTING.md) and our [Code of Conduct](CODE_OF_CONDUCT.md).
+We love contributions - bug reports, features, and docs fixes. See [CONTRIBUTING.md](CONTRIBUTING.md) and our [Code of Conduct](CODE_OF_CONDUCT.md).
To report a security vulnerability, follow [SECURITY.md](SECURITY.md) instead of opening a public issue.
diff --git a/RELEASING.md b/RELEASING.md
index 1d617ebe1..574cc9cae 100644
--- a/RELEASING.md
+++ b/RELEASING.md
@@ -1,58 +1,56 @@
# Releasing
-Two pipelines ship from this repo:
+This repository ships two independent release pipelines:
| What | Trigger | Workflow |
| ------------------------- | --------------------------- | ------------------------------------------------------------------------------------------------ |
-| Four public npm packages | Push to `main` (Changesets) | [`.github/workflows/release.yml`](.github/workflows/release.yml) |
+| npm packages | Push to `main` (Changesets) | [`.github/workflows/release.yml`](.github/workflows/release.yml) |
| Server image + Helm chart | Manual `workflow_dispatch` | [`.github/workflows/release-image-and-chart.yml`](.github/workflows/release-image-and-chart.yml) |
-They are independent. Publishing npm does not stamp or push the chart, and the chart workflow does not publish npm.
+Publishing npm does not stamp or push the chart. Publishing the image/chart does not publish npm.
-| Package | Source | Notes |
-| ----------------------------- | --------------------------- | ---------------------------------------------- |
-| `@truefoundry/trueforge-core` | `packages/harness` | Library. `files: ["dist"]`. |
-| `@truefoundry/trueforge` | `packages/server` | App + CLI. Tarball includes `dist/_frontend/`. |
-| `@truefoundry/trueforge-sdk` | `packages/sdk` | Fern-generated client. Do not hand-edit. |
-| `@truefoundry/trueforge-ui` | `packages/trueforge-ui-sdk` | Embeddable chat UI. |
+## Published packages
-`frontend` is private and is not published; the server build copies its output into `dist/_frontend/`.
+| Package | Source | Notes |
+| ----------------------------- | --------------------------- | --------------------------------------------------------------- |
+| `@truefoundry/trueforge-core` | `packages/harness` | Library (`files: ["dist"]`) |
+| `@truefoundry/trueforge` | `packages/server` | App + CLI; tarball includes embedded UI under `dist/_frontend/` |
+| `@truefoundry/trueforge-sdk` | `packages/sdk` | Fern-generated client — do not hand-edit |
+| `@truefoundry/trueforge-ui` | `packages/trueforge-ui-sdk` | Embeddable chat UI |
-Internal deps use `workspace:*`. On publish, pnpm rewrites those to the exact version in the dependency's `package.json`. `changeset publish` publishes in dependency order (core before server, sdk before ui), so a published dependent never points at an unpublished dep from the same run.
+`packages/frontend` is not published on its own. The server build copies its output into `@truefoundry/trueforge`'s `dist/_frontend/`.
+
+Workspace dependencies use `workspace:*`. On publish, pnpm rewrites them to the exact version in each dependency's `package.json`. `changeset publish` publishes in dependency order, so a package never lands pointing at an unpublished sibling from the same run.
---
-# Releasing npm packages
+# npm packages
-## Per-release flow
+## Release flow
There is no `v*` git-tag publish. One workflow both versions and publishes:
-1. **Land a changeset on `main`.** In the same PR as the code change:
+1. **Add a changeset** in the same PR as the code change:
```bash
pnpm changeset
- # or, non-interactive:
+ # non-interactive:
pnpm change --bump patch --summary "…" @truefoundry/trueforge-core
```
- Name only the packages that should bump. A dep can ship without its dependent (the dependent's `workspace:*` stays untouched until that package is itself changeset + published). SDK regen on a PR already adds `@truefoundry/trueforge-sdk` via `pnpm changeset:sdk-regen`.
+ Name only the packages that should bump. A dependency can ship without its dependents. SDK regeneration on a PR already adds `@truefoundry/trueforge-sdk` via `pnpm changeset:sdk-regen`.
-2. **Merge to `main`.** `.github/workflows/release.yml` runs. If `.changeset/*.md` files are pending, the job skips build/test (the Version Packages PR is gated by CI.yml) and `changesets/action` opens (or updates) a **Version Packages** PR. That PR is `pnpm run version`: `changeset version`, then `pnpm sdk:generate` only if `@truefoundry/trueforge-sdk`'s version actually moved (Fern rebakes version literals). Review the version bumps and CHANGELOGs, then merge.
+2. **Merge to `main`.** `.github/workflows/release.yml` runs. With pending `.changeset/*.md` files, `changesets/action` opens or updates a **Version Packages** PR (`pnpm run version`: `changeset version`, then `pnpm sdk:generate` only if the SDK version moved). Review bumps and changelogs, then merge.
-3. **Merging Version Packages publishes.** The same workflow sees no pending changesets and runs `pnpm release` (`pnpm build && changeset publish`). Auth is trusted publishing (OIDC — no `NPM_TOKEN`). pnpm 11 implements the OIDC token exchange natively. Watch the repo Actions tab.
+3. **Merge Version Packages to publish.** The same workflow sees no pending changesets and runs `pnpm release` (`pnpm build && changeset publish`). Auth is npm trusted publishing over GitHub OIDC (no `NPM_TOKEN`).
- **Dist-tags:** while `.changeset/pre.json` exists (`pnpm changeset pre enter rc`), publishes use the `rc` dist-tag, not `latest`. After `pnpm changeset pre exit`, the next Version Packages merge publishes to `latest`. Install an RC with `npx @truefoundry/trueforge@rc` or `@0.1.0-rc.1`; bare `npx @truefoundry/trueforge` stays on `latest`.
+ **Dist-tags:** while `.changeset/pre.json` exists (`pnpm changeset pre enter rc`), publishes use the `rc` tag. After `pnpm changeset pre exit`, the next Version Packages merge publishes to `latest`. Install an RC with `npx @truefoundry/trueforge@rc` or a concrete `x.y.z-rc.N` version.
-4. **Bump the pinned version in downstream consumers** (e.g. the gateway). Pin exact versions (no `^`) during the fast 0.x churn:
+4. **Update downstream pins** that depend on these packages. Prefer exact versions (no `^`) during early `0.x` churn.
- ```json
- "@truefoundry/trueforge-core": "0.x.y"
- ```
+`workflow_dispatch` on **Release** re-runs the same job (useful after a bot-only commit that did not re-trigger the workflow).
-`workflow_dispatch` on **Release** re-runs the same job (useful after a bot-only commit that GitHub did not chain into this workflow).
-
-A push to `main` with **no** pending changesets still runs `changeset publish`, which publishes any package whose current `package.json` version is not yet on npm and no-ops the rest. The first time this workflow lands on `main`, unpublished packages at `0.1.0-rc.1` will try to publish.
+A push to `main` with no pending changesets still runs `changeset publish`, which publishes any `package.json` version not yet on npm and no-ops the rest.
## Prerelease mode
@@ -60,60 +58,30 @@ Pre mode is repo-wide (`.changeset/pre.json`), not per-package. The repo is curr
| Goal | Command | Then |
| -------------------- | ----------------------------- | ------------------------------------------------------------------------- |
-| Stay on RCs | (already in pre) | Normal PRs + Version Packages. Versions look like `0.1.0-rc.N`. |
+| Stay on RCs | (already in pre) | Normal PRs + Version Packages. Versions look like `x.y.z-rc.N`. |
| Ship stable `latest` | `pnpm changeset pre exit` | Commit the deleted `pre.json`, merge, then merge the Version Packages PR. |
| Start a new RC line | `pnpm changeset pre enter rc` | Commit `pre.json`, merge, continue as above. |
-`pre enter` / `pre exit` do not bump versions or publish. The Version Packages PR is what versions; merging it is what publishes.
-
-Do not mix “this package stable, that package RC” in one `changeset version` — exit pre only when the next publish should be GA.
-
-## Publishing model (`@truefoundry/trueforge-core`)
-
-The package publishes from the package root (`packages/harness`), same as every other package in this repo. The build compiles every `src/**/*.ts` to its own `.js` (CJS) + `.mjs` (ESM) + `.d.ts` triple under `dist/`, and `package.json`'s `exports` map points at `./dist/...` paths; `files: ["dist"]` scopes the published tarball to just the compiled output. Consequences:
-
-- Deep imports keep the same specifier as before, e.g.
- `@truefoundry/trueforge-core/core/llm/LLMTypes` — the package's own `"./*"`
- export pattern maps that to `./dist/core/llm/LLMTypes.{d.ts,js,mjs}`
- internally, so no consumer using exports-aware resolution (`bundler`,
- `node16`, `nodenext`) needs to change anything. Only a genuinely legacy
- `moduleResolution: "node"`/`"node10"` consumer (which ignores `package.json`
- `exports` entirely and does literal on-disk path lookups) would need to add
- a `/dist/` segment or move to an exports-aware mode.
-- `require()` and `import` both work (`.js` is CJS, `.mjs` is ESM).
-- The curated barrels (`.`, `./core`, `./agent-session`) remain the public
- API; deep imports are the escape hatch for internals.
-- `package.json` is published as-is (no staged rewrite), and it also carries a
- `"trueforge-dev"` export condition pointing at `./src/*.ts`, used only
- for dist-free host dev inside this monorepo (`packages/server`'s
- `NODE_OPTIONS='--conditions=trueforge-dev'` scripts). `src/` is **not**
- in the tarball (`files: ["dist"]`), so that condition name must never be a
- string a consumer's tooling activates automatically — it deliberately isn't
- `"development"`, which Vite/webpack default to auto-activating in dev mode
- with no consumer opt-in (Vite's default `resolve.conditions` substitutes the
- literal string `"development"` whenever `NODE_ENV !== 'production'`). A
- genuinely custom condition name like this one is only ever reachable by an
- explicit `--conditions=trueforge-dev` opt-in, which no external
- consumer would ever set — so it ships as truly inert dead weight.
-
-> **Reality check we've accepted:** a public npm package is discoverable
-> regardless of its name (npm's public change feed is scraped, and the
-> package is listed on npmjs.com/org/truefoundry). Anything that must NOT be
-> effectively public should not ship in the tarball. Note: sourcemaps are
-> currently **enabled** (`sourcemap: true` in tsup, `declarationMap` in
-> tsconfig.build.json), which embeds/references original TypeScript source in
-> the published tarball — this is a deliberate, accepted trade-off for now.
-> Every deferred OSS item carries a `TODO(oss):` comment so we can grep for
-> them when that day comes.
+`pre enter` / `pre exit` do not bump versions or publish. The Version Packages PR versions; merging it publishes.
+
+Do not mix stable and RC packages in one `changeset version` — exit pre only when the next publish should be GA.
+
+## Package layout (`@truefoundry/trueforge-core`)
+
+Packages publish from their package root. The core build emits CJS (`.js`), ESM (`.mjs`), and `.d.ts` under `dist/`; `package.json` `exports` point at those paths and `files: ["dist"]` limits the tarball to compiled output.
+
+- Deep imports such as `@truefoundry/trueforge-core/core/llm/LLMTypes` resolve via the package `exports` map for modern `moduleResolution` modes (`bundler`, `node16`, `nodenext`).
+- Curated barrels (`.`, `./core`, `./agent-session`) are the supported public API; deep imports are an escape hatch.
+- A custom `"trueforge-dev"` export condition points at `./src` for dist-free monorepo development only. `src/` is not in the tarball, and the condition is not named `"development"`, so external tooling will not activate it accidentally.
+
+Sourcemaps / declaration maps are currently enabled in the published tarball.
## Why dependents pin exact versions
-`@truefoundry/trueforge` depends on `@truefoundry/trueforge-core: workspace:*` (and `@truefoundry/trueforge-ui` on the sdk the same way). On publish, pnpm rewrites that to the **version in the dependency's `package.json`**. If that version is missing from npm, `npx @truefoundry/trueforge` fails at runtime. Changeset both packages in the same Version Packages PR when the dependent uses new APIs from the dep.
+On publish, `workspace:*` becomes the **exact version** in the dependency's `package.json`. If that version is missing from npm, consumers fail at install/runtime. Changeset both packages together when a dependent needs new APIs from its dependency.
## Local iteration without publishing
-For tight loops, skip the publish round-trip:
-
```bash
pnpm clean && pnpm build && pnpm standalone:start
# or pack only:
@@ -121,103 +89,64 @@ cd packages/harness && pnpm build && pnpm pack
cd packages/server && pnpm pack
```
-Point consumers at a tarball via a `file:` dependency (or use `yalc`).
-Publish a real version when CI or teammates need it.
+Point consumers at a tarball with a `file:` dependency (or `yalc`) until a real version is published.
## npm trusted publishing
-Each of the four packages must list this repo + workflow as a trusted publisher on npmjs.com:
+Each of the four packages must list this repository and workflow as a trusted publisher on npmjs.com:
- Repository: `truefoundry/trueforge`
-- Workflow filename: `release.yml` (must match exactly; renaming the file breaks publish)
-- No environment name (the job does not use a GitHub Environment)
+- Workflow filename: `release.yml` (must match exactly)
+- No GitHub Environment name (the job does not use one)
-Packages that have never been published need that trusted-publisher row **before** the first `changeset publish` (npm allows creating a package via OIDC when the org is configured for it). `@truefoundry/trueforge-core` already publishes this way; sdk / ui / server need the same config before they can land.
+Configure the trusted-publisher row **before** the first `changeset publish` for a new package. Do not set `NPM_TOKEN` or an `_authToken` in `.npmrc` on the release job — that disables the OIDC exchange.
## Troubleshooting
-- **Version Packages PR never appears**: no `.changeset/*.md` on `main` (only `config.json` / `README.md` / `pre.json` stay). Add a changeset in a PR and merge, or run **Release** via `workflow_dispatch`.
-- **Publish fails requiring a tag**: prerelease versions need the `rc` dist-tag. `changeset publish` sets that while pre mode is on; for a local publish use `pnpm publish --tag rc`.
-- **Publish fails with 403/E403**: version already published (npm versions are immutable — add a changeset and merge Version Packages again), or the trusted publisher config doesn't match the workflow filename/repo exactly.
-- **OIDC/auth error in the publish step**: trusted publishing requires pnpm >= 11.0.7 (native OIDC; `pnpm/action-setup@v4` reads the pinned version from root `packageManager`) and the npmjs.com trusted publisher config matching exactly. Do not set `NPM_TOKEN` — a registry `_authToken` disables the OIDC exchange.
-- **Missing `dist/_frontend/index.html`**: root `pnpm build` must build `frontend` before `@truefoundry/trueforge`; the release job fails closed if the copy is absent.
-- **Version PR did not regenerate the SDK**: `scripts/version.mjs` only runs `pnpm sdk:generate` when `@truefoundry/trueforge-sdk`'s version changed. That step needs Docker on the runner (already true on `ubuntu-latest`).
-
-## Deferred to the real OSS release — grep for `TODO(oss)`
+- **Version Packages PR never appears** — no `.changeset/*.md` on `main` (only `config.json` / `README.md` / `pre.json` remain). Add a changeset and merge, or run **Release** via `workflow_dispatch`.
+- **Publish fails requiring a tag** — prerelease versions need the `rc` dist-tag. `changeset publish` sets that while pre mode is on; for a local publish use `pnpm publish --tag rc`.
+- **Publish fails with 403/E403** — version already published (npm versions are immutable), or the trusted publisher config does not match the workflow filename/repo exactly.
+- **OIDC/auth error** — requires pnpm >= 11.0.7 (native OIDC; `pnpm/action-setup@v4` reads `packageManager` from the root) and a matching trusted publisher config. Remove any registry `_authToken`.
+- **Missing `dist/_frontend/index.html`** — root `pnpm build` must build `frontend` before `@truefoundry/trueforge`; the release job fails closed if the copy is absent.
+- **Version PR did not regenerate the SDK** — `scripts/version.mjs` only runs `pnpm sdk:generate` when `@truefoundry/trueforge-sdk`'s version changed. That step needs Docker (available on `ubuntu-latest`).
-Done: root LICENSE + MIT license fields, CONTRIBUTING, SECURITY,
-CODE_OF_CONDUCT, issue/PR templates.
+---
-| Item | Where |
-| ---------------------------------------------------------------------------------- | ------------------------------------------------------- |
-| Ship README (currently no `README.md` in `packages/harness`, npm page stays blank) | packages/harness |
-| Add `--provenance` to publish | .github/workflows/release.yml |
-| Private-repo links in shipped sandbox scripts | packages/harness/src/core/sandbox/scripts/mcp_client.py |
-| Sourcemaps/declarationMap decision | packages/harness/tsup.config.ts, tsconfig.build.json |
-| CODEOWNERS / CI for external (fork) PRs | .github/ |
-| Secret-scan history, enable secret scanning + push protection, flip repo public | GitHub settings |
+# Server image and Helm chart
----
+A separate pipeline ships the deployable artifacts: the server container image (API + UI, built from the root `Dockerfile`) and the `charts/trueforge` Helm chart. It is driven by `.github/workflows/release-image-and-chart.yml` and runs only on manual **`workflow_dispatch`** (Actions → **Release image and Helm chart** → Run workflow).
-# Releasing the server image + Helm chart
+Install a published chart with:
-A separate pipeline ships the deployable artifacts: the server container image
-(API + UI, built from the root `Dockerfile`) and the `charts/trueforge` Helm
-chart. It is driven by `.github/workflows/release-image-and-chart.yml` and runs
-only on manual **`workflow_dispatch`** (Actions → "Release image and Helm chart"
-→ Run workflow).
+```bash
+helm install trueforge oci://tfy.jfrog.io/tfy-helm/trueforge \
+ --version <x.y.z>
+```
## What the workflow does
The dispatch commit SHA is the image tag. The workflow:
-1. **Builds and pushes the image** via the shared reusable workflow
- `truefoundry/github-workflows-public/.github/workflows/build.yml@main` to the
- JFrog public Artifactory repo, tagged with `github.sha`. The chart pulls the
- image from JFrog, so JFrog is the only publish target (public ECR is disabled).
-2. **Stamps the chart in the runner workspace** — sets `Chart.yaml`
- `version` to `0.0.0-<sha>` (Helm SemVer-compatible prerelease), and
- `appVersion` / `image.tag` to the raw SHA. It does **not** commit those
- stamps back to `main`.
-3. **Publishes the chart** — packages `charts/trueforge` and pushes it to
- the JFrog public OCI Helm repo. It does not attach artifacts to a GitHub
- Release.
+1. **Builds and pushes the image** via `truefoundry/github-workflows-public/.github/workflows/build.yml@main` to the public JFrog Artifactory repository, tagged with `github.sha`.
+2. **Stamps the chart in the runner workspace** — sets `Chart.yaml` `version` to `0.0.0-<sha>` (Helm SemVer-compatible prerelease), and `appVersion` / `image.tag` to the raw SHA. Those stamps are **not** committed back to `main`.
+3. **Publishes the chart** — packages `charts/trueforge` and pushes it to the JFrog public OCI Helm repository (`oci://tfy.jfrog.io/tfy-helm`). It does not attach artifacts to a GitHub Release.
## Per-release flow
-1. On the commit you want to ship, run the workflow from the Actions tab (or
- `gh workflow run release-image-and-chart.yml`).
-2. Watch the run. The image and chart land in JFrog; the job summary prints the
- image URI.
-
-> Publishing the npm packages is a separate pipeline (`release.yml`) triggered
-> by pushes to `main` via Changesets. It is independent of this image/chart
-> workflow.
+1. On the commit you want to ship, run the workflow from the Actions tab (or `gh workflow run release-image-and-chart.yml`).
+2. Watch the run. The image and chart land in JFrog; the job summary prints the image URI.
## Required repository configuration
-Org/repo **variables**: `TRUEFOUNDRY_ARTIFACTORY_REGISTRY_URL`,
-`TRUEFOUNDRY_ARTIFACTORY_PUBLIC_REPOSITORY`,
-`TRUEFOUNDRY_ARTIFACTORY_PUBLIC_HELM_REPOSITORY`.
+**Variables:** `TRUEFOUNDRY_ARTIFACTORY_REGISTRY_URL`, `TRUEFOUNDRY_ARTIFACTORY_PUBLIC_REPOSITORY`, `TRUEFOUNDRY_ARTIFACTORY_PUBLIC_HELM_REPOSITORY`.
-Org/repo **secrets**: `TRUEFOUNDRY_ARTIFACTORY_PUBLIC_USERNAME`,
-`TRUEFOUNDRY_ARTIFACTORY_PUBLIC_PASSWORD`.
+**Secrets:** `TRUEFOUNDRY_ARTIFACTORY_PUBLIC_USERNAME`, `TRUEFOUNDRY_ARTIFACTORY_PUBLIC_PASSWORD`.
-## Bundled dependencies
+## Bundled chart dependencies
-The chart bundles Postgres and Redis as optional Bitnami subcharts, declared in
-`charts/trueforge/Chart.yaml` against the public Bitnami OCI archive
-(`oci://registry-1.docker.io/bitnamicharts`) and pinned by the committed
-`Chart.lock`. The workflow fetches them with `helm dependency build` before
-packaging (the archive is public, no auth). Disable them with
-`postgresql.enabled=false` / `redis.enabled=false` to target external services.
+The chart optionally bundles Postgres and Redis (Bitnami subcharts from `oci://registry-1.docker.io/bitnamicharts`, pinned by `Chart.lock`). The workflow runs `helm dependency build` before packaging. Disable them with `postgresql.enabled=false` / `redis.enabled=false` to use external services.
-**Images vs charts.** Bitnami left the charts public but relocated their
-container images to `docker.io/bitnamilegacy` (frozen, no security updates). So
-`charts/trueforge/values.yaml` overrides the subchart images to pinned legacy
-tags mirrored to the TrueFoundry JFrog registry, and sets
-`global.security.allowInsecureImages: true` (required once the registry differs
-from Bitnami's default). Mirror the images once per pinned tag:
+Bitnami left the charts public but moved versioned container images to `docker.io/bitnamilegacy`. `charts/trueforge/values.yaml` points the subcharts at pinned tags mirrored on JFrog and sets `global.security.allowInsecureImages: true`. Mirror once per pinned tag:
```bash
for img in \
@@ -230,17 +159,13 @@ done
# redis-exporter:1.76.0-debian-12-r0
```
-To bump a bundled version: change the version under `dependencies:` in
-`Chart.yaml`, run `pnpm chart:deps` to refresh `Chart.lock`, then update the
-matching `image.tag` in `values.yaml` and mirror that new legacy tag to JFrog.
+To bump a bundled version: change `dependencies:` in `Chart.yaml`, run `pnpm chart:deps`, update the matching `image.tag` in `values.yaml`, and mirror the new legacy tag to JFrog.
## Validating the chart locally
-Fetch the subchart deps first (public archive, no auth), then lint/template:
-
```bash
-pnpm chart:deps # helm dependency build (writes charts/, uses Chart.lock)
+pnpm chart:deps # helm dependency build (uses Chart.lock)
pnpm chart:lint # helm lint with charts/trueforge/ci/lint-values.yaml
-pnpm chart:template # render the manifests
+pnpm chart:template # render manifests
pnpm chart:package # package to dist/ (gitignored)
```
diff --git a/charts/trueforge/README.md b/charts/trueforge/README.md
index 4966783bc..969487bed 100644
--- a/charts/trueforge/README.md
+++ b/charts/trueforge/README.md
@@ -11,6 +11,24 @@ The chart version, `appVersion`, and `image.tag` are stamped at publish time by
(manual `workflow_dispatch`, commit SHA as the image tag). Committed chart
values are placeholders until that workflow runs.
+## Dev defaults (read before exposing)
+
+A bare `helm install` is intentionally easy for local / private-cluster trials.
+Those defaults are **not** production-safe:
+
+| Default | Risk if the Service / Ingress is reachable |
+| --- | --- |
+| `configs.oidc.enabled: false` | No login; every caller is the shared local admin (`trueforge-default`) |
+| `postgresql.auth.password: trueforge` | Well-known Postgres password (unless you set `existingSecret` / a strong password) |
+| `redis.auth.enabled: false` | Unauthenticated Redis on the cluster network |
+
+Before exposing TrueForge beyond a trusted network: enable OIDC, change or
+Secret-back the Postgres password, and prefer external passworded Redis (or
+keep Redis ClusterIP-only and NetworkPolicy-restricted). See
+[Production checklist](#production-checklist) and the
+[Setup Login](https://github.com/truefoundry/trueforge/blob/main/docs/authentication/overview.mdx)
+docs.
+
## Dependencies
Postgres and Redis ship as **bundled** dependencies (the Bitnami `postgresql`
@@ -31,7 +49,7 @@ Disable either dependency to point at an external service instead (see below).
## Install
```bash
-helm install trueforge oci://<jfrog-public-helm-repo>/trueforge \
+helm install trueforge oci://tfy.jfrog.io/tfy-helm/trueforge \
--version <x.y.z>
```
@@ -39,16 +57,18 @@ Optional: set the public origin once you expose the service (needed for MCP OAut
and OIDC callbacks):
```bash
-helm upgrade --install trueforge oci://<jfrog-public-helm-repo>/trueforge \
+helm upgrade --install trueforge oci://tfy.jfrog.io/tfy-helm/trueforge \
--version <x.y.z> \
--set server.publicBaseUrl=https://trueforge.example.com
```
## Postgres
-Bundled by default (`postgresql.enabled=true`). Set `postgresql.auth.username`,
-`postgresql.auth.password` (or Bitnami's `postgresql.auth.existingSecret`), and
-`postgresql.auth.database`; the server connects to it automatically.
+Bundled by default (`postgresql.enabled=true`). The chart ships a **dev**
+password (`trueforge`). Change `postgresql.auth.password` or set
+Bitnami's `postgresql.auth.existingSecret` before any shared / public deploy.
+Also set `postgresql.auth.username` and `postgresql.auth.database` as needed;
+the server connects to the bundled instance automatically.
To use an **external** Postgres, set `postgresql.enabled=false` and provide
`externalPostgres.host` (+ `port`, `database`, `user`). Set
@@ -70,9 +90,10 @@ externalPostgres:
## Redis
The server always runs peered (`STANDALONE=false`), so Redis is always required.
-Bundled by default (`redis.enabled=true`, auth disabled). To use an **external**
-Redis, set `redis.enabled=false` and provide `externalRedis.url` as a string or
-`valueFrom.secretKeyRef`:
+Bundled by default (`redis.enabled=true`, **auth disabled** — fine only when
+Redis stays unreachable outside the cluster trust boundary). To use an
+**external** Redis, set `redis.enabled=false` and provide `externalRedis.url`
+as a string or `valueFrom.secretKeyRef`:
```yaml
redis:
@@ -90,9 +111,11 @@ For passworded Redis, prefer an external instance and load `REDIS_URL` via
## OIDC
-Configure IdP login under `configs.oidc`. When `enabled` is false, no `OIDC_*`
-env is set (fixed local admin identity). When enabled, set string `issuerUrl`
-and `clientId`, and `clientSecret` as a string or `valueFrom.secretKeyRef`
+Configure IdP login under `configs.oidc`. When `enabled` is false (the default),
+no `OIDC_*` env is set and the server uses a **fixed local admin** identity —
+anyone who can reach the API/UI has full admin access. Enable OIDC for any
+shared or public deployment. When enabled, set string `issuerUrl` and
+`clientId`, and `clientSecret` as a string or `valueFrom.secretKeyRef`
(prefer valueFrom in production).
Also set `server.publicBaseUrl` to the public origin and register
@@ -189,10 +212,12 @@ Also available (defaults inert): `strategy`, `priorityClassName`,
## Production checklist
+- **Enable `configs.oidc`** — leaving it off grants shared admin to anyone who can reach the server.
+- **Replace the bundled Postgres password** (`trueforge`) or set `postgresql.auth.existingSecret`.
+- Treat bundled Redis (`redis.auth.enabled: false`) as cluster-internal only, or switch to external passworded Redis via `externalRedis.url`.
- Set `server.publicBaseUrl` to the real public origin before using MCP OAuth or OIDC.
- Prefer `valueFrom.secretKeyRef` for Postgres password, Redis URL, and OIDC client secret; do not commit secrets in values files.
- Prefer external managed Postgres/Redis over the bundled subcharts for production HA.
- Set container `resources` (especially CPU requests) before enabling HPA.
-- Add `imagePullSecrets` when pulling from `tfy.jfrog.io`.
-- Configure IdP login via `configs.oidc` when you need OIDC.
+- Default `tfy.jfrog.io` images and the Helm chart are anonymously pullable — set `imagePullSecrets` only if you override to a private registry.
- Enable `podDisruptionBudget` when running multiple replicas (defaults to `minAvailable: 1`; set exactly one of `minAvailable` or `maxUnavailable`).
diff --git a/charts/trueforge/templates/NOTES.txt b/charts/trueforge/templates/NOTES.txt
index c6bab284a..739092f63 100644
--- a/charts/trueforge/templates/NOTES.txt
+++ b/charts/trueforge/templates/NOTES.txt
@@ -14,6 +14,26 @@ Postgres: {{ if .Values.postgresql.enabled }}bundled ({{ include "trueforge.post
Redis: {{ if .Values.redis.enabled }}bundled{{- else }}external (literal or valueFrom){{- end }}
OIDC: {{ if .Values.configs.oidc.enabled }}enabled{{- else }}disabled (local admin identity){{- end }}
+{{- if not .Values.configs.oidc.enabled }}
+
+WARNING: OIDC is disabled. Anyone who can reach the API/UI is the shared local
+admin (trueforge-default). Enable configs.oidc before exposing this release
+beyond a trusted network.
+{{- end }}
+
+{{- if and .Values.postgresql.enabled (eq (default "" .Values.postgresql.auth.existingSecret) "") (eq (default "" .Values.postgresql.auth.password) "trueforge") }}
+
+WARNING: Bundled Postgres is using the chart's well-known dev password
+(trueforge). Set postgresql.auth.password or postgresql.auth.existingSecret
+before any shared / public deploy.
+{{- end }}
+
+{{- if and .Values.redis.enabled (not .Values.redis.auth.enabled) }}
+
+WARNING: Bundled Redis has auth disabled. Keep it cluster-internal (NetworkPolicy)
+or switch to external passworded Redis via externalRedis.url.
+{{- end }}
+
{{- if and .Values.configs.oidc.enabled (not .Values.server.publicBaseUrl) }}
WARNING: configs.oidc.enabled is true but server.publicBaseUrl is empty.
diff --git a/charts/trueforge/values.yaml b/charts/trueforge/values.yaml
index 3758d3068..728c3ad1b 100644
--- a/charts/trueforge/values.yaml
+++ b/charts/trueforge/values.yaml
@@ -10,6 +10,8 @@ image:
pullPolicy: IfNotPresent
imagePullSecrets: []
+# Default tfy.jfrog.io repos are anonymously pullable. Set secrets only when
+# overriding image.repository / subchart registries to a private registry.
nameOverride: ""
fullnameOverride: ""
@@ -61,7 +63,9 @@ server:
# { valueFrom: { secretKeyRef: ... } }.
configs:
oidc:
- # When false, no OIDC_* env is set (fixed local admin identity).
+ # Dev default: false → no OIDC_* env; fixed local admin identity
+ # (trueforge-default). Anyone who can reach the API/UI is admin.
+ # Enable for any shared or public deployment.
enabled: false
issuerUrl: ""
clientId: ""
@@ -100,11 +104,12 @@ postgresql:
repository: tfy-mirror/bitnamilegacy/postgresql
tag: 17.6.0-debian-12-r4
auth:
- username: truefoundry_utils
- database: truefoundry_utils
- # Dev default. In production set a strong password or reference a Secret via
- # `existingSecret` (Bitnami reads the user password from key `password`).
- password: truefoundry_utils
+ username: trueforge
+ database: trueforge
+ # Dev default password (publicly known). Before any shared/public deploy,
+ # set a strong password or reference a Secret via `existingSecret`
+ # (Bitnami reads the user password from key `password`).
+ password: trueforge
existingSecret: ""
primary:
persistence:
@@ -112,9 +117,10 @@ postgresql:
size: 8Gi
# --- Bundled Redis (Bitnami subchart) ------------------------------------------
-# Rendered only when redis.enabled is true. Auth is disabled so REDIS_URL is a
-# plain redis://host:6379 the server can consume directly. For passworded Redis,
-# disable the subchart and use externalRedis with a Secret.
+# Rendered only when redis.enabled is true. Auth is disabled (dev default) so
+# REDIS_URL is a plain redis://host:6379. Safe only while Redis stays inside
+# the cluster trust boundary. For passworded Redis, disable the subchart and
+# use externalRedis with a Secret.
redis:
enabled: true
architecture: standalone
@@ -134,8 +140,8 @@ redis:
externalPostgres:
host: ""
port: 5432
- database: truefoundry_utils
- user: truefoundry_utils
+ database: trueforge
+ user: trueforge
# string, or { valueFrom: { secretKeyRef: { name, key } } }. Prefer valueFrom in prod.
password: ""
# password:
diff --git a/docs/assets/trueforge-black.svg b/docs/assets/trueforge-black.svg
new file mode 100644
index 000000000..08d5127d7
--- /dev/null
+++ b/docs/assets/trueforge-black.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/assets/trueforge-white.svg b/docs/assets/trueforge-white.svg
new file mode 100644
index 000000000..a46d05feb
--- /dev/null
+++ b/docs/assets/trueforge-white.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/authentication/overview.mdx b/docs/authentication/overview.mdx
index 3fe7dae14..287145037 100644
--- a/docs/authentication/overview.mdx
+++ b/docs/authentication/overview.mdx
@@ -23,6 +23,7 @@ The default. Do **not** set any `OIDC_*` variables, run TrueForge as usual ([Qui
<Warning>
Use this only on `localhost` or behind network controls you trust. On a public host, anyone who can reach the server gets full admin access under one shared identity.
+ The Helm chart defaults to this mode (`configs.oidc.enabled: false`) plus a well-known bundled Postgres password and Redis without auth — see the [chart README](https://github.com/truefoundry/trueforge/blob/main/charts/trueforge/README.md#dev-defaults-read-before-exposing) before exposing a release.
</Warning>
## Option B — enable OIDC login
diff --git a/docs/quickstart.mdx b/docs/quickstart.mdx
index 5df07464d..f47db4b9e 100644
--- a/docs/quickstart.mdx
+++ b/docs/quickstart.mdx
@@ -41,8 +41,7 @@ TrueForge runs in [two modes](/introduction#two-ways-to-run-it): **local mode**
The Helm chart deploys the server in hosted mode with bundled Postgres and Redis (or point it at your own):
```bash
- # TODO: replace <HELM_REPO> with the published Helm repo URL
- helm install trueforge oci://<HELM_REPO>/trueforge \
+ helm install trueforge oci://tfy.jfrog.io/tfy-helm/trueforge \
--version <x.y.z>
```
@@ -52,7 +51,7 @@ TrueForge runs in [two modes](/introduction#two-ways-to-run-it): **local mode**
| `postgresql.enabled` | `true` | Bundle Postgres; set `false` + `externalPostgres.*` to bring your own. |
| `redis.enabled` | `true` | Bundle Redis; set `false` + `externalRedis.url` (string or `valueFrom`). |
| `server.publicBaseUrl` | `""` | Public origin; required for OIDC and MCP OAuth callbacks. |
- | `configs.oidc.enabled` | `false` | Enable IdP login via `configs.oidc.*` (see chart README). |
+ | `configs.oidc.enabled` | `false` | Enable IdP login via `configs.oidc.*`. Default off = shared local admin — see [chart README](https://github.com/truefoundry/trueforge/blob/main/charts/trueforge/README.md#dev-defaults-read-before-exposing). |
</Tab>
</Tabs>
diff --git a/packages/server/.env.example b/packages/server/.env.example
index 7fb5f91ea..3cc1275fc 100644
--- a/packages/server/.env.example
+++ b/packages/server/.env.example
@@ -41,10 +41,10 @@ PORT=8790
# STANDALONE=false
## Absolute path to the SQLite database file. Used when STANDALONE=true;
-## defaults to the OS data dir from env-paths (app name "truefoundry-utils"):
-## macOS: ~/Library/Application Support/truefoundry-utils/db/db.sqlite
-## Linux: ~/.local/share/truefoundry-utils/db/db.sqlite
-## Windows: %LOCALAPPDATA%\truefoundry-utils\Data\db\db.sqlite
+## defaults to the OS data dir from env-paths (app name "trueforge"):
+## macOS: ~/Library/Application Support/trueforge/db/db.sqlite
+## Linux: ~/.local/share/trueforge/db/db.sqlite
+## Windows: %LOCALAPPDATA%\trueforge\Data\db\db.sqlite
# SQLITE_PATH=
## Used when STANDALONE=false (ignored in standalone). Redis connection URL for
@@ -105,12 +105,13 @@ REDIS_URL=redis://localhost:6379
## ---------------------------------------------------------------------------
## Postgres (used when STANDALONE=false; also read by Compose postgres
## services via env_file). Config defaults match these values if unset.
-## Keep localhost here for host `pnpm dev`;
+## Local-dev credentials only (trueforge/trueforge) — change them for any shared
+## or networked host. Keep localhost here for host `pnpm dev`;
## `docker-compose.yml` overrides POSTGRES_HOST/PORT for the server container.
## ---------------------------------------------------------------------------
-POSTGRES_USER=harness
-POSTGRES_PASSWORD=harness
-POSTGRES_DB=harness
+POSTGRES_USER=trueforge
+POSTGRES_PASSWORD=trueforge
+POSTGRES_DB=trueforge
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
## Max connections in the pg Pool. Optional, defaults to 10.
@@ -122,7 +123,9 @@ POSTGRES_PORT=5432
## ---------------------------------------------------------------------------
## OIDC (used when STANDALONE=false). All three must be set together, or all
-## left unset. Unset = fixed local admin identity (no IdP). Ignored in standalone.
+## left unset. Unset = fixed local admin identity (no IdP) — anyone who can
+## reach the server is admin. Enable OIDC for shared/public hosts. Ignored in
+## standalone.
## ---------------------------------------------------------------------------
# OIDC_ISSUER_URL=https://your-tenant.example.com/oauth2/default
# OIDC_CLIENT_ID=
diff --git a/packages/server/scripts/migrate-legacy-sqlite-path.mjs b/packages/server/scripts/migrate-legacy-sqlite-path.mjs
index 5b12a84d9..4df0bab25 100644
--- a/packages/server/scripts/migrate-legacy-sqlite-path.mjs
+++ b/packages/server/scripts/migrate-legacy-sqlite-path.mjs
@@ -1,58 +1,74 @@
/**
- * Temporary layout migrate for the default standalone SQLite path:
- * `{env-paths data}/db.sqlite*` → `{env-paths data}/db/db.sqlite*`
+ * One-shot migrate for the default standalone SQLite data dir rename:
+ * env-paths("truefoundry-utils")/db/db.sqlite* → env-paths("trueforge")/db/db.sqlite*
*
- * - No legacy files → noop.
- * - `db/` already has db.sqlite + db.sqlite-shm + db.sqlite-wal → noop.
- * - Otherwise replace `db/` by copying legacy files, then best-effort delete
+ * Assumes the earlier flat → `db/` layout move under truefoundry-utils already
+ * ran for existing installs. This only relocates that `db/` tree to the new
+ * app name.
+ *
+ * - No legacy `db/` files → noop.
+ * - Destination already has db.sqlite + db.sqlite-shm + db.sqlite-wal → noop.
+ * - Otherwise replace destination `db/` by copying, then best-effort delete
* the legacy copies (warn only if delete fails).
*
- * Used by root `prestandalone:dev` / `:no-watch`. Remove once the package
- * rename lands and this path layout is no longer transitional.
+ * Used by root `prestandalone:dev` / `:no-watch`.
*/
import { copyFileSync, existsSync, mkdirSync, readdirSync, rmSync, unlinkSync } from 'node:fs';
import path from 'node:path';
import envPaths from 'env-paths';
-const ENV_PATHS_APP_NAME = 'truefoundry-utils';
+const LEGACY_ENV_PATHS_APP_NAME = 'truefoundry-utils';
+const ENV_PATHS_APP_NAME = 'trueforge';
const SQLITE_BASENAME = 'db.sqlite';
const COMPLETE_DEST_FILES = ['db.sqlite', 'db.sqlite-shm', 'db.sqlite-wal'];
-function isLegacySqliteFileName(name) {
+function isSqliteFileName(name) {
return name === SQLITE_BASENAME || name.startsWith(`${SQLITE_BASENAME}-`);
}
-const dataDir = envPaths(ENV_PATHS_APP_NAME, { suffix: '' }).data;
-if (!existsSync(dataDir)) {
+const legacyDataDir = envPaths(LEGACY_ENV_PATHS_APP_NAME, { suffix: '' }).data;
+const legacyDbDir = path.join(legacyDataDir, 'db');
+if (!existsSync(legacyDbDir)) {
process.exit(0);
}
-const legacyNames = readdirSync(dataDir).filter(isLegacySqliteFileName);
+const legacyNames = readdirSync(legacyDbDir).filter(isSqliteFileName);
if (legacyNames.length === 0) {
process.exit(0);
}
-const newDir = path.join(dataDir, 'db');
-if (COMPLETE_DEST_FILES.every(name => existsSync(path.join(newDir, name)))) {
+const newDbDir = path.join(envPaths(ENV_PATHS_APP_NAME, { suffix: '' }).data, 'db');
+if (COMPLETE_DEST_FILES.every(name => existsSync(path.join(newDbDir, name)))) {
process.exit(0);
}
-rmSync(newDir, { recursive: true, force: true });
-mkdirSync(newDir, { recursive: true });
+rmSync(newDbDir, { recursive: true, force: true });
+mkdirSync(newDbDir, { recursive: true });
for (const name of legacyNames) {
- const source = path.join(dataDir, name);
- const destination = path.join(newDir, name);
+ const source = path.join(legacyDbDir, name);
+ const destination = path.join(newDbDir, name);
console.log(`Moving ${source} → ${destination}`);
copyFileSync(source, destination);
}
for (const name of legacyNames) {
- const source = path.join(dataDir, name);
+ const source = path.join(legacyDbDir, name);
try {
unlinkSync(source);
} catch (error) {
console.warn(`Could not remove legacy ${source}:`, error instanceof Error ? error.message : error);
}
}
+
+try {
+ if (existsSync(legacyDbDir) && readdirSync(legacyDbDir).length === 0) {
+ rmSync(legacyDbDir, { recursive: true, force: true });
+ }
+} catch (error) {
+ console.warn(
+ `Could not remove empty legacy dir ${legacyDbDir}:`,
+ error instanceof Error ? error.message : error,
+ );
+}
diff --git a/packages/server/src/config.ts b/packages/server/src/config.ts
index ac2f763e2..32317210a 100644
--- a/packages/server/src/config.ts
+++ b/packages/server/src/config.ts
@@ -8,7 +8,7 @@
*
* `STANDALONE` is a discriminated mode selector:
* - `true` (default): SQLite only; no Redis / executor peering.
- * - `false`: Postgres + Redis (defaults to local harness credentials /
+ * - `false`: Postgres + Redis (defaults to local trueforge credentials /
* `redis://localhost:6379`).
*/
import { existsSync } from 'node:fs';
@@ -26,10 +26,10 @@ const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)),
/** Turn ids minted by a standalone process; no peer can ever own them. */
const LOCAL_EXECUTOR_ID = 'local';
/** OS-standard data dir for SQLite in standalone mode. */
-const ENV_PATHS_APP_NAME = 'truefoundry-utils';
-const DEFAULT_POSTGRES_USER = 'harness';
-const DEFAULT_POSTGRES_PASSWORD = 'harness';
-const DEFAULT_POSTGRES_DB = 'harness';
+const ENV_PATHS_APP_NAME = 'trueforge';
+const DEFAULT_POSTGRES_USER = 'trueforge';
+const DEFAULT_POSTGRES_PASSWORD = 'trueforge';
+const DEFAULT_POSTGRES_DB = 'trueforge';
const DEFAULT_POSTGRES_HOST = 'localhost';
const DEFAULT_POSTGRES_PORT = 5432;
const DEFAULT_REDIS_URL = 'redis://localhost:6379';
diff --git a/packages/trueforge-ui-sdk/NOTICE b/packages/trueforge-ui-sdk/NOTICE
index 454f88d6b..0d5e6e730 100644
--- a/packages/trueforge-ui-sdk/NOTICE
+++ b/packages/trueforge-ui-sdk/NOTICE
@@ -7,11 +7,11 @@ This distribution may include or depend on third-party software. Notable
dependencies and their licenses include (non-exhaustive):
- @assistant-ui/react / @assistant-ui/core — see their respective LICENSE files
-- tfy-web-components — see its LICENSE
- @openuidev/react-ui and related OpenUI packages — see their LICENSE files
-- @fortawesome/fontawesome-svg-core and related packages — Font Awesome Free license
-- @mui/material and @emotion/* — see their respective LICENSE files
+- @truefoundry/assistant-ui-runtime — see its LICENSE
- lucide-react — ISC / Lucide license
+- monaco-editor — see its LICENSE
+- react-markdown / remark-gfm / react-syntax-highlighter — see their respective LICENSE files
Full license texts for installed packages are available in node_modules under
each package's LICENSE (or equivalent) file.
diff --git a/packages/trueforge-ui-sdk/README.md b/packages/trueforge-ui-sdk/README.md
index d3d9d53cc..c080ed261 100644
--- a/packages/trueforge-ui-sdk/README.md
+++ b/packages/trueforge-ui-sdk/README.md
@@ -1,6 +1,6 @@
# @truefoundry/trueforge-ui
-[CI](https://github.com/truefoundry/harness/actions/workflows/ci.yml)
+[CI](https://github.com/truefoundry/trueforge/actions/workflows/ci.yml)
[npm](https://www.npmjs.com/package/@truefoundry/trueforge-ui)
[License](./LICENSE)
diff --git a/packages/trueforge-ui-sdk/docs/api.md b/packages/trueforge-ui-sdk/docs/api.md
index e0c94f59b..3748be884 100644
--- a/packages/trueforge-ui-sdk/docs/api.md
+++ b/packages/trueforge-ui-sdk/docs/api.md
@@ -1,8 +1,11 @@
# Public API
-Curated exports from `@truefoundry/trueforge-ui`. Design-system **component
-values** (`Button`, `Modal`, …) live on `tfy-web-components` — this package
-re-exports override **types** only where needed.
+Curated exports from `@truefoundry/trueforge-ui`. Design-system primitives
+(`CenteredModal`, `Switch`, …) are owned in this package. Low-level controls
+like `Button` / `IconButton` are styled via theme tokens / CSS (not
+`SlotsProvider` slots); their **prop types** (`ButtonProps`, `IconButtonProps`,
+…) are exported for hosts that build around those contracts. Component
+**values** appear below only when they are part of the public surface.
## Quick start
@@ -71,10 +74,10 @@ const server = createTrueForgeAgentUIServer({ baseUrl: '/', token });
## Types for overrides
-| Export | Notes |
-| ---------------------------------------------- | ------------------------ |
-| `ButtonProps`, `ButtonSize`, `IconButtonProps` | Slot override contracts |
-| Atom `*Props` types | Per-atom override shapes |
+| Export | Notes |
+| ---------------------------------------------- | ---------------------------------------------------------------- |
+| `ButtonProps`, `ButtonSize`, `IconButtonProps` | Prop contracts for in-package primitives (tokens/CSS, not slots) |
+| Atom `*Props` types | Per-atom override shapes |
## Styles
diff --git a/packages/trueforge-ui-sdk/docs/compatibility.md b/packages/trueforge-ui-sdk/docs/compatibility.md
index a557e3638..dc18cac5d 100644
--- a/packages/trueforge-ui-sdk/docs/compatibility.md
+++ b/packages/trueforge-ui-sdk/docs/compatibility.md
@@ -37,11 +37,11 @@ hosts may override via `theme.icons` or register custom SVGR components.
Chrome hooks (`useAui`, `useAuiState`, `useTheme`) are re-exported from
`@truefoundry/trueforge-ui` — prefer those so the host shares the SDK instance.
-When importing deep `@assistant-ui/react` primitives, `@assistant-ui/core`, or
-`tfy-web-components` from host code, also add them as direct dependencies at
-versions within the ranges above so resolution is app-rooted. Force a
-singleton (Vite `dedupe`, Yarn `resolutions`, npm `overrides`) so the SDK and
-host share one copy — see README Troubleshooting.
+When importing deep `@assistant-ui/react` primitives or `@assistant-ui/core`
+from host code, also add them as direct dependencies at versions within the
+ranges above so resolution is app-rooted. Force a singleton (Vite `dedupe`,
+Yarn `resolutions`, npm `overrides`) so the SDK and host share one copy — see
+README Troubleshooting.
## Singletons
@@ -49,4 +49,3 @@ These must resolve to one physical copy in the dependency graph:
- `react` / `react-dom`
- `@assistant-ui/core` / `@assistant-ui/react` / `@assistant-ui/store`
-- `tfy-web-components` (for shared theme context)