Update READMEs for npm

.changeset/20260816223810-regenerate-sdk-from-openapi.md

@@ -0,0 +1,5 @@
+---
+'@truefoundry/trueforge-sdk': patch
+---
+
+Regenerate SDK from updated OpenAPI spec.

.github/fern/generators.yml

@@ -2,13 +2,15 @@
 #
 # openapi/openapi.json is committed by `pnpm openapi:write`, so Fern never needs the server.
 readme:
+  apiName: TrueForge
   introduction: >
-    TypeScript client for the TrueForge agent harness server: a self-hosted
+    TypeScript client for the TrueForge Agent Harness Server: a self-hosted
     runtime that executes agent turns and streams them over Server-Sent Events.
 
 
     When auth is enabled on the server, pass an ID token via the optional `token`
     client option (`Authorization: Bearer`).
+  apiReferenceLink: https://trueforge.dev/api/use-agent
   # Fern keys this lookup on the stream flag, so the string form misses and fails.
   defaultEndpoint:
     method: POST

README.md

@@ -26,6 +26,20 @@
     <img src="https://img.shields.io/badge/SDK-trueforge.dev/api/overview-blue.svg" alt="SDK">
   </a>
 </p>
+<p align="center">
+  <a href="https://www.npmjs.com/package/@truefoundry/trueforge">
+    <img src="https://img.shields.io/npm/v/@truefoundry/trueforge?label=trueforge" alt="npm @truefoundry/trueforge">
+  </a>
+  <a href="https://www.npmjs.com/package/@truefoundry/trueforge-sdk">
+    <img src="https://img.shields.io/npm/v/@truefoundry/trueforge-sdk?label=trueforge-sdk" alt="npm @truefoundry/trueforge-sdk">
+  </a>
+  <a href="https://www.npmjs.com/package/@truefoundry/trueforge-ui">
+    <img src="https://img.shields.io/npm/v/@truefoundry/trueforge-ui?label=trueforge-ui" alt="npm @truefoundry/trueforge-ui">
+  </a>
+  <a href="https://www.npmjs.com/package/@truefoundry/trueforge-core">
+    <img src="https://img.shields.io/npm/v/@truefoundry/trueforge-core?label=trueforge-core" alt="npm @truefoundry/trueforge-core">
+  </a>
+</p>
 
 # TrueForge
 

RELEASING.md

@@ -13,7 +13,7 @@ Publishing npm does not stamp or push the chart. Publishing the image/chart does
 
 | Package                       | Source                    | Notes                                                           |
 | ----------------------------- | ------------------------- | --------------------------------------------------------------- |
-| `@truefoundry/trueforge-core` | `packages/trueforge-core` | Library (`files: ["dist"]`)                                     |
+| `@truefoundry/trueforge-core` | `packages/trueforge-core` | Library (`files: ["dist", "README.md"]`)                        |
 | `@truefoundry/trueforge`      | `packages/trueforge`      | App + CLI; tarball includes embedded UI under `dist/_frontend/` |
 | `@truefoundry/trueforge-sdk`  | `packages/trueforge-sdk`  | Fern-generated client — do not hand-edit                        |
 | `@truefoundry/trueforge-ui`   | `packages/trueforge-ui`   | Embeddable chat UI                                              |
@@ -68,7 +68,7 @@ Do not mix stable and RC packages in one `changeset version` — exit pre only w
 
 ## 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.
+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", "README.md"]` keeps `src/` out of the tarball.
 
 - 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.

packages/trueforge-core/AGENTS.md

@@ -1,3 +1,3 @@
-- Workspace source MUST remain ESM so `exports["trueforge-dev"]` can load `src/` without a build. That condition name MUST NOT be `"development"` (or `"production"`) — the package publishes from its own root with `files: ["dist"]`, so `src/` is never in the tarball, and Vite/webpack default to auto-activating a literal `"development"` condition in dev mode with no consumer opt-in, which would break resolution for any such consumer. `dist/` output MUST expose CJS `.js` and ESM `.mjs` outputs alongside `.d.ts`.
+- Workspace source MUST remain ESM so `exports["trueforge-dev"]` can load `src/` without a build. That condition name MUST NOT be `"development"` (or `"production"`) — the package publishes from its own root with `files: ["dist", "README.md"]`, so `src/` is never in the tarball, and Vite/webpack default to auto-activating a literal `"development"` condition in dev mode with no consumer opt-in, which would break resolution for any such consumer. `dist/` output MUST expose CJS `.js` and ESM `.mjs` outputs alongside `.d.ts`.
 - Top-level public package surfaces (`core`, `agent-session`, and other exported entrypoints) MAY use optional (`?`) properties for caller ergonomics.
 - Within this package, records, snapshots, store INPUT types, and other internal contracts MUST NOT use `?`. Absence MUST be an explicit required `| null` or `| undefined` field; prefer `null` for domain absence and `undefined` only when update/patch semantics must distinguish “not provided” from “clear.” Public surfaces adapt by supplying those explicit absences when calling inward. This forces internal object literals to be exhaustive under `tsc`, preventing forgotten fields and silent data loss.

packages/trueforge-core/README.md

@@ -0,0 +1,27 @@
+# @truefoundry/trueforge-core
+
+[Documentation](https://trueforge.dev) · [npm](https://www.npmjs.com/package/@truefoundry/trueforge-core) · [GitHub](https://github.com/truefoundry/trueforge)
+
+The agent execution library behind [TrueForge](https://trueforge.dev): the runtime that runs the agent loop — model calls, MCP tools, skills, sandboxing, approvals, context management, and session state.
+
+## Use TrueForge instead
+
+This package is the library the TrueForge server is built on. It is **not** a complete product on its own.
+
+If you want HTTP APIs, a TypeScript SDK, and a chat UI, use [`@truefoundry/trueforge`](https://www.npmjs.com/package/@truefoundry/trueforge) and start at **[trueforge.dev](https://trueforge.dev)**.
+
+```bash
+npx @truefoundry/trueforge
+```
+
+- [Quickstart](https://trueforge.dev/quickstart)
+- [HTTP API & SDK](https://trueforge.dev/api/overview)
+- [Chat UI](https://trueforge.dev/chat-ui)
+
+## Compatibility
+
+`@truefoundry/trueforge-core` does **not** offer backward compatibility guarantees at this time. Public APIs and types may change in any release. Pin an exact version if you depend on this package.
+
+## License
+
+[MIT](https://github.com/truefoundry/trueforge/blob/main/LICENSE)

packages/trueforge-core/package.json

@@ -1,15 +1,15 @@
 {
   "name": "@truefoundry/trueforge-core",
   "version": "0.1.0",
-  "description": "TrueForge core library",
+  "description": "TrueForge Agent Harness library.",
   "author": "TrueFoundry",
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/truefoundry/trueforge.git",
     "directory": "packages/trueforge-core"
   },
-  "homepage": "https://github.com/truefoundry/trueforge/tree/main/packages/trueforge-core#readme",
+  "homepage": "https://trueforge.dev",
   "bugs": {
     "url": "https://github.com/truefoundry/trueforge/issues"
   },
@@ -79,7 +79,8 @@
     "./package.json": "./package.json"
   },
   "files": [
-    "dist"
+    "dist",
+    "README.md"
   ],
   "engines": {
     "node": ">=22"

packages/trueforge-core/scripts/check-dist.mjs

@@ -46,8 +46,9 @@ if (!fs.existsSync(distPkgPath)) {
   }
 }
 
-// package.json is published as-is (no more staged dist/package.json rewrite), and only
-// `dist` ships (files: ["dist"]) — so a literal "development" condition pointing at
+// package.json is published as-is (no more staged dist/package.json rewrite), and
+// `src/` does not ship (files: ["dist", "README.md"]) — so a literal "development"
+// condition pointing at
 // ./src/... would be a live, resolvable-but-broken promise for any consumer whose
 // tooling defaults to activating it, not dead weight. Vite's default resolve.conditions
 // is ['module', 'browser', 'development|production'], which it substitutes to the literal

packages/trueforge-sdk/README.md

@@ -1,15 +1,16 @@
-# Truefoundry TypeScript Library
+# TrueForge TypeScript Library
 
 [![fern shield](https://img.shields.io/badge/%F0%9F%8C%BF-Built%20with%20Fern-brightgreen)](https://buildwithfern.com?utm_source=github&utm_medium=github&utm_campaign=readme&utm_source=Truefoundry%2FTypeScript)
 [![npm shield](https://img.shields.io/npm/v/@truefoundry/trueforge-sdk)](https://www.npmjs.com/package/@truefoundry/trueforge-sdk)
 
-TypeScript client for the TrueForge agent harness server: a self-hosted runtime that executes agent turns and streams them over Server-Sent Events.
+TypeScript client for the TrueForge Agent Harness Server: a self-hosted runtime that executes agent turns and streams them over Server-Sent Events.
 
 When auth is enabled on the server, pass an ID token via the optional `token` client option (`Authorization: Bearer`).
 
 
 ## Table of Contents
 
+- [Documentation](#documentation)
 - [Installation](#installation)
 - [Reference](#reference)
 - [Usage](#usage)
@@ -31,6 +32,10 @@ When auth is enabled on the server, pass an ID token via the optional `token` cl
   - [Runtime Compatibility](#runtime-compatibility)
 - [Contributing](#contributing)
 
+## Documentation
+
+API reference documentation is available [here](https://trueforge.dev/api/use-agent).
+
 ## Installation
 
 ```sh

packages/trueforge/README.md

@@ -0,0 +1,30 @@
+# @truefoundry/trueforge
+
+[Documentation](https://trueforge.dev) · [Quickstart](https://trueforge.dev/quickstart) · [npm](https://www.npmjs.com/package/@truefoundry/trueforge) · [GitHub](https://github.com/truefoundry/trueforge)
+
+The open-source agent harness — the runtime that turns an LLM into a working agent.
+
+TrueForge runs the agent loop (model calls, MCP tools, skills, sandboxing, approvals, context management, and session state) and exposes it as a **chat UI**, an **HTTP API**, and a TypeScript **SDK**.
+
+## Quick start
+
+Requires [Node.js](https://nodejs.org) 22+.
+
+```bash
+npx @truefoundry/trueforge
+```
+
+Open [http://localhost:8790](http://localhost:8790). This is local mode (one process, SQLite) — for your machine only.
+
+## Docs
+
+Guides, hosted deployment, API reference, and the UI SDK live at **[trueforge.dev](https://trueforge.dev)**.
+
+## Related packages
+
+- [`@truefoundry/trueforge-sdk`](https://www.npmjs.com/package/@truefoundry/trueforge-sdk) — TypeScript client for the HTTP API
+- [`@truefoundry/trueforge-ui`](https://www.npmjs.com/package/@truefoundry/trueforge-ui) — embeddable React chat UI
+
+## License
+
+[MIT](https://github.com/truefoundry/trueforge/blob/main/LICENSE)

packages/trueforge/package.json

@@ -1,15 +1,15 @@
 {
   "name": "@truefoundry/trueforge",
   "version": "0.1.0",
-  "description": "TrueForge agent server + UI (npx @truefoundry/trueforge)",
+  "description": "TrueForge Agent Harness: server, HTTP API, and chat UI (npx @truefoundry/trueforge)",
   "author": "TrueFoundry",
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/truefoundry/trueforge.git",
     "directory": "packages/trueforge"
   },
-  "homepage": "https://github.com/truefoundry/trueforge/tree/main/packages/trueforge#readme",
+  "homepage": "https://trueforge.dev",
   "bugs": {
     "url": "https://github.com/truefoundry/trueforge/issues"
   },
@@ -21,7 +21,8 @@
   "type": "module",
   "bin": "./dist/cli.js",
   "files": [
-    "dist"
+    "dist",
+    "README.md"
   ],
   "engines": {
     "node": ">=22"