Prompted by user feedback: *"The documentation doesn't always reflect
the latest release. Some articles are outdated or incomplete."*
I audited every English page under `packages/twenty-docs` against the
code at v2.27.0, verifying each checkable claim (commands, env vars,
enum members, payload shapes, prop tables, API routes) against source in
`packages/`. Anything without a `file:line` citation proving the docs
wrong was dropped.
**Result: 414 findings across 226 pages — 75 critical, 169 major, 170
minor.** The feedback is accurate, and understates it in the
developer-facing sections.
This PR fixes a first slice. The full findings list is below so the rest
can be picked up.
---
## What this PR changes
**Removes the `twenty-ui` component reference** (25 English pages + 325
translations). The section predated the extraction of the design system
into the `twenty-ui` package:
- Not one import path resolved. `twenty-ui/display` and
`twenty-ui/components` are not export subpaths (real ones:
`data-display`, `feedback`, `icon`, `input`, `navigation`, `surfaces`,
`layout`, …), and ~20 more examples imported `@/ui/...` paths no longer
in twenty-front.
- Three documented components no longer exist: `SoonPill`,
`AutosizeTextInput`, `MenuItemCommand`.
- `Chip`'s props table documented the deleted `EntityChip`.
`ProgressBar`'s entire API was replaced
(`duration`/`delay`/`easing`/`barHeight`/`autoStart` →
`value`/`barColor`/`countdownDurationInMs`/…).
It was also unreachable from the navigation, so the pages were indexed
and searchable but maintained by nobody. Storybook is the live source of
truth here, which is why this is a deletion rather than a repair.
**Legal FAQ.** Corrects the workspace deletion timeline to match clause
4.9 of the DPA the product itself generates (~90 days from live systems,
a further ~90 for backups, isolated throughout) instead of the previous
claim of immediate removal with 7-day backup retention. Rephrases the
support-access answer to describe what the product actually does: access
is on by default and can be disabled in Settings → General → Security,
rather than the previous claim that it requires the customer to report
an issue and grant access.
**Self-hosting setup page.** The SMTP configuration block used
`<ArticleTabs>/<ArticleTab>`, leftovers from the pre-Mintlify site.
Those components are undefined here, so the Gmail/Office365/smtp4dev
instructions were not rendering at all. Converted to `<Tabs>/<Tab>`.
**Removes a fabricated Enterprise gate.** A Warning on the app
publishing page claimed cross-workspace sharing of tarball apps requires
an Enterprise key and that the Distribution tab shows an upgrade prompt.
No such gate exists in code, and its link target didn't exist either.
**Link and asset fixes.** Retargeted the two `docs.json` redirects whose
destinations 404'd; fixed the Code of Conduct link (file lives under
`.github/`); fixed the app-roles example link to
`examples/hello-world/src/roles/default-role.ts`; pointed the Contribute
frontend card, four `/developers/extend/apps/getting-started` links and
one `/twenty-ui/display` link at real pages; dropped two `<img>` tags
whose files are absent from the repo.
After this PR: every internal link and image reference resolves, all 171
navigation entries resolve to a file, and no redirect destination is
dead.
---
## Audit: what else is wrong
### Root causes
The failures aren't random rot. Four mechanisms produce nearly all of
them:
1. **Nothing links renaming a symbol to updating the page that documents
it.** Whole pages describe APIs returning zero grep hits:
`MessageQueueServiceBase`, `useScopedHotkeys`/`PageHotkeyScope`,
`@Gate`, `SoonPill`.
2. **"Coming soon" is written once and never revisited.** Nine features
are documented as unavailable that have shipped.
3. **Pages are dropped from navigation but left on disk.** 55 were
unreachable yet still indexed and searchable.
4. **Docs written from intent rather than from code.** One case is
provably born-stale: the `front-components` limitations table was
written in a commit that landed *after* the commit which polyfilled the
APIs it lists as unsupported.
### Priority 1: pages that actively break the reader
**Workflow template variables are wrong across 12 pages.** The largest
cluster — 16 critical findings, one root cause. Record-event triggers
expose the record under `properties.after`/`properties.before`; manual
triggers under `payload`; webhook triggers store the posted body flat
with no wrapper. Docs use `{{trigger.object.*}}`, `{{trigger.body.*}}`,
`{{trigger.subject}}` throughout. Search Records returns `{ first, all,
totalCount }`, not an array, and the resolver is Handlebars, which
doesn't accept `[0]` indexing at all — so `{{searchRecords[0].name}}`
and `{{searchRecords.length}}` cannot work. Iterator exposes
`currentItem`, not `item`/`index`. Evidence:
`generate-fake-object-record-event.ts:44-60`,
`workflow-schema.workspace-service.ts:501-517`,
`find-records.workflow-action.ts:111-117`,
`workflow-iterator-result.type.ts:2-3`,
`twenty-shared/src/utils/evalFromContext.ts`. Every workflow tutorial on
the site is copy-paste-broken. Highest-value fix in the audit, and
mostly mechanical.
**Self-hosting runbook commands don't work.** Backup names a container
and database that don't exist (service is `db` → `twenty-db-1`; database
is `default`, not `twenty`). Restore runs `docker compose stop
twenty-server twenty-front`, neither of which is a service — the compose
file defines `server`, `worker`, `db`, `redis`, and there's no separate
frontend service. The "unable to log in" fix runs `yarn` and `npx nx
database:reset` inside the production container, whose Dockerfile
deletes `npm`/`npx` and ships only `dist/`. Someone following the backup
page ends up with no backup.
**API, webhook and OAuth contracts are wrong.** The documented webhook
payload (`event`, `data`, `timestamp`) is not what the server sends —
the real body is `targetUrl`, `eventName`, `objectMetadata`,
`workspaceId`, `webhookId`, `eventDate`, `userId`, `workspaceMemberId`,
`record`, optional `updatedFields`
(`transform-event-batch-to-webhook-events.ts:34-46`). Any integration
written from that page fails to parse. `GET /oauth/authorize` doesn't
exist (server serves `/oauth/register`, `/token`, `/revoke`,
`/introspect`; authorization is served by the frontend at `/authorize`).
`/oauth/register` never returns a `client_secret` —
`token_endpoint_auth_method` is hard-coded `'none'` — so the documented
response and the "store it securely" warning are fiction, and the Client
Credentials section is unusable with a DCR client. PKCE is mandatory,
not "recommended". Batch limit is 200, not 60 (`QUERY_MAX_RECORDS =
200`), making the derived throughput estimates ~3.3x off.
**Contributor onboarding teaches removed APIs.** `queue.mdx`,
`hotkeys.mdx` and `feature-flags.mdx` are wrong at essentially every
step. Documented nx targets `twenty-server:database:migrate:prod`,
`twenty-server:test:unit` and `npx nx start` aren't real targets and
fail outright. `local-setup.mdx` never mentions
`packages/twenty-utils/setup-dev-env.sh`, the supported entry point.
Both style guides teach the `${({ theme }) => ...}` pattern, which now
returns **zero** hits in twenty-front against 929 files using
`themeCssVariables`. `frontend-commands.mdx` still lists Craco; the
frontend is Vite.
**SSO configuration is substantially fiction.** Twenty supports exactly
two protocols, OIDC and SAML. The docs omit OIDC entirely, present
Google Workspace and Microsoft Entra ID (separate social-login toggles)
as SSO providers, list configuration fields matching neither form, and
instruct the reader to click a **Test Configuration** button that exists
nowhere in the codebase.
**Data model.** The field-type table documents two types that don't
exist (`Domain`, `Long Text`) and omits three users can actually pick
(`Files`, `Full Name`, `Rich Text`). The filter-operator table is wrong
for every field type listed: Text has none of its four documented
operators, Date is missing six of nine.
**Import guidance that fails silently.** `DD/MM/YYYY` is documented as
supported; import uses plain `new Date(value)`, so `15/03/2024` is
always rejected and `03/15/2024` always read US-style — and the sibling
`fix-import-errors.mdx` says the opposite. The company sample CSV is
unusable as written (`Domain / Domain Label` headers don't exist; real
ones are `Domain Name / Link Label`).
### Priority 2: shipped features documented as unavailable
This is the specific complaint in the feedback. Each is a one-line fix.
| Documented as | Reality |
|---|---|
| AI Agent action "Coming soon" (2 pages) |
`WorkflowActionType.AI_AGENT` ships, in the picker, no feature flag |
| "There is no built-in if/else logic" (2 pages) |
`WorkflowActionType.IF_ELSE` ships |
| Webhook event filtering "may be added in future releases" (2 pages) |
per-webhook `operations` array with `*.created` / `person.*` / `*.*`
wildcards |
| Many-to-many "coming in H2 2026" | Junction Relations shipped as
public beta; Twenty's own how-to documents it |
| Email campaigns "available soon" (2 pages) | MessageCampaign object,
send/stats jobs, unsubscribe topics all ship |
| CC/BCC "not yet available" | exists on Send Email |
| Workflow retry "on our roadmap" | run-level retry command plus
per-step `retryOnFailure` |
| front-components limitations table | `getBoundingClientRect`,
`offset*`/`client*`/`scroll*`, `getComputedStyle`, `getElementById` all
polyfilled |
| Node SDK "does not exist" | `twenty-client-sdk@2.27.0` ships and is
documented elsewhere in these docs |
Four "coming soon" claims were checked and are **still accurate** —
webhook trigger authentication, dashboard-level filters, dashboard
timezone, background-job priority. Leave them.
One needs rewording rather than promotion: **gauge charts** are
described as on the roadmap, but the upgrade command
`2-3-workspace-command-...-delete-gauge-widgets` says support was
*removed*.
### Priority 3: structural
**30 orphaned pages remain** after the twenty-ui deletion: 15 of 18
`developers/contribute/*`, all 6 `user-guide/getting-started/*`, plus
`self-host.mdx`, `key-rotation.mdx`, `extend.mdx`,
`views-pipelines/overview.mdx`, `ai/capabilities/mcp.mdx`,
`data-migration/how-tos/export-faq.mdx`,
`extend/capabilities/{apis,webhooks}.mdx`. Each needs an explicit
decision: re-add, or delete plus redirect. Two look worth re-adding
rather than deleting — `user-guide/ai/capabilities/mcp.mdx` is accurate,
documents a shipped feature that's a plan line-item, and is reachable
only via a legacy redirect; `views-pipelines/overview.mdx` is linked
from three in-nav pages.
`user-guide/getting-started/capabilities/implementation-services.mdx`
must be merged rather than deleted, since three in-nav pages deep-link
it.
**Duplicate pages.** `getting-started/core-concepts/glossary.mdx` and
`user-guide/getting-started/capabilities/glossary.mdx` are 99%
identical. `developers/extend/webhooks.mdx` and
`developers/extend/capabilities/webhooks.mdx` are 88% identical and
carry the same wrong payload. `workflow-branches.mdx` and
`use-branches-in-workflows.mdx` are both in the sidebar and give
*contradictory* branch-creation instructions.
**Other.** 44 pages have no frontmatter `description`. The Russian
locale is 14 pages behind every other locale, including the entire
document-generator tutorial.
### Still needs a human owner
The legal FAQ promises breach notification "within 48 hours" while
clause 4.6 of the generated DPA (`dpa-template.constant.ts:178`) targets
72. Per direction, the docs keep 48h — a stricter public commitment than
the contract is a deliberate choice — but the DPA and the docs still
disagree, and someone owning the DPA should decide which moves.
Claims about SOC 2, GDPR attestation, backup cadence and AI-training use
could not be substantiated from the repository either way and need the
same treatment.
### Preventing recurrence
Three cheap guards would have caught most of the 75 criticals:
- **A CI check** that every navigation page resolves, every internal
link and image resolves, and no `.mdx` outside `l/` is orphaned. Catches
the entire structural third. This PR leaves the docs in a state where
such a check would pass.
- **Generate the volatile tables from their source enums** — field
types, workflow actions and triggers, filter operands, permission flags,
chart types, env vars — rather than hand-maintaining them. These
accounted for a large share of the major findings.
- **Treat "coming soon" as an expiring assertion**: tag each with the
symbol it depends on and fail the docs build when that symbol appears in
code.
## Suggested order for the rest
1. Workflow variable syntax across the 12 tutorial pages — largest
cluster, mechanical, most directly matches the feedback.
2. Self-host backup/restore/troubleshooting commands — highest blast
radius per reader.
3. Webhook payload and OAuth endpoints — blocks integrators.
4. The nine "coming soon" claims — one line each, and the most visible
form of "docs don't reflect the latest release".
5. Decide the 30 remaining orphans.
## Test plan
- [x] Every internal link and image reference in the docs resolves
- [x] All 171 navigation entries resolve to a file on disk
- [x] No `docs.json` redirect destination is dead
- [x] No inbound links to the deleted `twenty-ui` pages remain
- [x] `docs.json` structure intact after edit (138 redirects, 14
languages)
- [ ] Visual check of the self-hosting SMTP tabs once the docs preview
builds
---
_Generated by [Claude
Code](https://claude.ai/code/session_01AnUNYYdkN3PMTPb2m6CnqC)_
<!-- This is an auto-generated description by cubic. -->
<a
href="https://cubic.dev/pr/twentyhq/twenty/pull/23616?utm_source=github"
target="_blank" rel="noopener noreferrer"
data-no-image-dialog="true"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://www.cubic.dev/buttons/review-in-cubic-dark.svg"><source
media="(prefers-color-scheme: light)"
srcset="https://www.cubic.dev/buttons/review-in-cubic-light.svg"><img
alt="Review in cubic"
src="https://www.cubic.dev/buttons/review-in-cubic-dark.svg"></picture></a>
<!-- End of auto-generated description by cubic. -->
Closestwentyhq/core-team-issues#2742
A logic function run is capped by its own `timeoutSeconds` (900s max),
so anything that can't finish in one run — a full re-sync, a per-record
fan-out, a rate-limited third-party API — had no way to continue. This
adds a way to hand that work to the workers.
## What it looks like for an app author
```ts
import { enqueueJob } from 'twenty-sdk/logic-function';
await enqueueJob({
logicFunctionUniversalIdentifier: '9f1c3d7e-51b8-4a29-8f0d-7c4e2a6b1d33',
payload: { cursor: nextCursor },
retryLimit: 3,
priority: 2,
delayMs: 60_000,
});
```
The target runs in its own process with its own timeout budget. The
classic shape is a function that enqueues *itself* with the next cursor
until there is nothing left.
## Changes
**twenty-shared** — `EnqueueJobInput` / `EnqueueJobOptions` /
`EnqueueJobResult` in `application`.
**twenty-server** — new `application-job` module under
`core-modules/application`, following the `application-key-value`
pattern:
- `enqueueJob` mutation on the metadata API, `@AuthApplication`-scoped
- the lookup is scoped to `applicationId` + `workspaceId` — that's the
authorization boundary, an app can only enqueue its own logic functions,
anything else is `LOGIC_FUNCTION_NOT_FOUND`
- pushes a `LogicFunctionTriggerJob` onto the existing
`logicFunctionQueue`, so the enqueued run goes through the same executor
(and the same execution throttling) as every other trigger
- the queued run inherits the caller's `userId`/`userWorkspaceId`, so
its app access token carries the same permissions as the function that
queued it
**Job options** are range-checked via `ResolverValidationPipe`, since
the values come from application code and an unbounded delay or retry
count would let an app pin work in the shared queue:
| Option | Default | Range |
|--------|---------|-------|
| `retryLimit` | `0` | `0`–`10` |
| `priority` | queue default | `1`–`10` (lower first) |
| `delayMs` | `0` | `0`–7 days |
`retryLimit` defaults to `0` rather than inheriting the server-route
path's `3`: retries re-run the whole handler, so opting in should be the
author's explicit choice.
**twenty-sdk** — `enqueueJob` in `twenty-sdk/logic-function`, same shape
as `runAgent`/`kv`.
**Docs** — new "Background Jobs" page under Extend → Apps → Logic, plus
nav and overview entries.
**Generated** — regenerated `twenty-front/src/generated-metadata` and
`twenty-client-sdk/src/metadata/generated` for the new mutation.
## Tests
- `application-job.service.spec.ts` — 5 unit tests: job options mapping,
defaults, acting-user propagation, application-scoped lookup, not-found
- `enqueue-job.integration-spec.ts` — 5 integration tests: rejects a
non-`APPLICATION_ACCESS` token, enqueues a function the app owns,
rejects a function owned by another application, rejects an unknown
identifier, rejects out-of-range options
All green locally, along with `typecheck` for
`twenty-server`/`twenty-sdk` and oxlint/oxfmt on the touched files.
## Notes for review
- The target is addressed by `universalIdentifier`, matching `runAgent({
agentUniversalIdentifier })` and
`ServerRouteDispatchResult.targetLogicFunctionUniversalIdentifier`.
Addressing by `name` would be friendlier, but logic function names
aren't validated for uniqueness within an app — happy to add it as a
convenience if you'd rather.
- `enqueueJob` returns as soon as the job is accepted; it can't return
the target's result, since the queue driver's `add` returns void.
Documented, with a pointer to the KV store for handing results back.
---
_Generated by [Claude
Code](https://claude.ai/code/session_01QrYvGonS3HMdeuMAVjs5hR)_
<!-- This is an auto-generated description by cubic. -->
<a
href="https://cubic.dev/pr/twentyhq/twenty/pull/23527?utm_source=github"
target="_blank" rel="noopener noreferrer"
data-no-image-dialog="true"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://www.cubic.dev/buttons/review-in-cubic-dark.svg"><source
media="(prefers-color-scheme: light)"
srcset="https://www.cubic.dev/buttons/review-in-cubic-light.svg"><img
alt="Review in cubic"
src="https://www.cubic.dev/buttons/review-in-cubic-dark.svg"></picture></a>
<!-- End of auto-generated description by cubic. -->
---------
Co-authored-by: github-actions <github-actions@twenty.com>
## What
Adds a docs page teaching app developers how to reference auto-created
**system fields** (`createdAt`, `updatedAt`, `id`, …) from views and
other entities, and makes the API it documents real by exporting
`generateDefaultFieldUniversalIdentifier` from the SDK.
## Why
System fields are provisioned by the server, so they're never declared
with `defineField()` and have no importable `universalIdentifier`
constant. Since 2.19 their universal identifier is derived
deterministically from the application id, the object id and the field
name. Hardcoding an invented id fails sync with `INVALID_VIEW_DATA:
Field metadata not found` (this is exactly what broke the
twenty-partners `createdAt` view column).
The twenty-partners app already imports
`generateDefaultFieldUniversalIdentifier` from `twenty-sdk/define`, but
the function was never exported from the SDK. This PR adds the export
and documents the pattern.
## Changes
- **New page** `data/system-fields.mdx` — "Targeting System Fields":
- Lists the 8 system fields (`id`, `createdAt`, `updatedAt`,
`deletedAt`, `createdBy`, `updatedBy`, `position`, `searchVector`).
- Explains the deterministic derivation and the sync error from
hardcoding ids.
- Documents `generateDefaultFieldUniversalIdentifier({
applicationUniversalIdentifier, objectUniversalIdentifier, fieldName })`
with a full `defineView` example.
- Contrasts with standard objects (use
`STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.<object>.fields.<field>.universalIdentifier`)
and notes that `name` is a default, not system, field.
- **SDK export** — new `generate-default-field-universal-identifier.ts`
wrapping the existing `getFieldUniversalIdentifier` from
`twenty-shared/application` (`name` → `fieldName`), exported from
`define/index.ts`.
- Registered the page in `docs.json` (Data group) and cross-linked it
from the Views doc.
## Notes
`node_modules` isn't installed in this environment, so `nx typecheck`
wasn't run. The wrapper is a signature-matched pass-through and the
`twenty-shared/application` subpath + `getFieldUniversalIdentifier`
barrel export were both verified to exist.
---
_Generated by [Claude
Code](https://claude.ai/code/session_017B7VivHcqZYjn3ukestY9U)_
<!-- This is an auto-generated description by cubic. -->
<a
href="https://cubic.dev/pr/twentyhq/twenty/pull/22856?utm_source=github"
target="_blank" rel="noopener noreferrer"
data-no-image-dialog="true"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://www.cubic.dev/buttons/review-in-cubic-dark.svg"><source
media="(prefers-color-scheme: light)"
srcset="https://www.cubic.dev/buttons/review-in-cubic-light.svg"><img
alt="Review in cubic"
src="https://www.cubic.dev/buttons/review-in-cubic-dark.svg"></picture></a>
<!-- End of auto-generated description by cubic. -->
---------
Co-authored-by: github-actions <github-actions@twenty.com>
## What & why
This adds a **guided tutorial** that teaches the Twenty SDK by building
one real, useful app end to end — plus the finished app itself, ready
for the marketplace.
The app, **Document Generator**, turns reusable templates into
personalized documents using CRM data: write a template once with
`{{placeholders}}`, then generate a filled-in document for any Person or
Company from the command menu, an AI agent, or a workflow.
## Two parts
**1. The app — `packages/twenty-apps/public/document-generator`**
Each capability maps to one tutorial chapter:
- **Data:** `documentTemplate` + `document` objects, fields, and a
bidirectional relation
- **Logic:** a single `generate-document` handler exposed as an **AI
tool**, a **workflow action**, and an **HTTP POST route**; plus a public
**HTML view route**
- **UI:** two views + sidebar navigation, a **command-menu item** (on
Person selection) that opens a **React front component**
- **AI:** an agent + skill; a default application role; marketplace
metadata + logo
- **Tests:** unit tests for the template renderer + an install
integration test
**2. The tutorial —
`packages/twenty-docs/.../apps/tutorials/document-generator/`**
A six-chapter series under **Developers › Apps › Tutorial** (Overview →
Data model → Generating documents → HTTP routes → Building the UI → AI
agent → Publishing). Minimal prose, paste-ready code, inline links to
the matching reference pages, and real screenshots. Registers a new
"Tutorial" nav group and regenerates `docs.json` + the navigation
template.
## Verification
Validated against a running Twenty instance (`twenty-app-dev` on
`:2020`):
- `twenty dev --once` installs cleanly (28 metadata objects created)
- Generated a real document from a Person — placeholders resolved (name,
job title, `company.name`, email), zero missing tokens
- Command menu → front component → generate flow works in the UI
- Public HTML view route renders the document
- App gates green: `yarn lint` (0/0), `yarn typecheck`, `yarn test:unit`
(7/7)
All screenshots in the tutorial are captured from this run.
## Notes
- Left out per-app CI workflows (`.github/workflows`) to keep scope
tight — happy to add them if wanted.
https://claude.ai/code/session_012FoC76zPbPmpgtN7MXMPwy
---
_Generated by [Claude
Code](https://claude.ai/code/session_012FoC76zPbPmpgtN7MXMPwy)_
<!-- This is an auto-generated description by cubic. -->
<a
href="https://cubic.dev/pr/twentyhq/twenty/pull/22522?utm_source=github"
target="_blank" rel="noopener noreferrer"
data-no-image-dialog="true"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://www.cubic.dev/buttons/review-in-cubic-dark.svg"><source
media="(prefers-color-scheme: light)"
srcset="https://www.cubic.dev/buttons/review-in-cubic-light.svg"><img
alt="Review in cubic"
src="https://www.cubic.dev/buttons/review-in-cubic-dark.svg"></picture></a>
<!-- End of auto-generated description by cubic. -->
---------
Co-authored-by: github-actions <github-actions@twenty.com>
## What
Lets app **front components** localize the strings they render,
extending the
existing application-translation pipeline (which today only covers
manifest
labels) to component source. App authors mark strings with a small,
familiar
API; the build extracts and bakes them; the runtime resolves them for
the
user's locale.
```tsx
import { Trans, t, msg, useTranslate } from 'twenty-sdk/front-component';
<Trans>Loading postcard…</Trans>
<Trans context="card-title">Untitled</Trans> // disambiguation
const empty = t('No content yet…'); // works outside JSX
<p>{t('Saved {count} cards', { count })}</p> // interpolation
const STATUSES = [{ id: 'draft', label: msg('Draft') }]; // lazy descriptor
```
## How
- **Runtime** (`twenty-sdk/front-component`): `t()` (eager, usable
anywhere —
event handlers, helpers, module scope), `msg()` (lazy descriptor),
`<Trans>`
(reactive JSX), `useTranslate()` / `useLocale()`. Source-string
fallback,
`{name}` interpolation, and `context` disambiguation. No build-time
macro —
these are plain runtime functions.
- **Extraction**: a `ts-morph` scan collects `t()`/`msg()`/`<Trans>`
strings
from component source into the same `locales/*.json` catalogs the
manifest
pipeline already writes (`twenty dev:translations-extract`).
- **Delivery**: `twenty dev:build` bakes the compiled per-locale catalog
into
each front-component bundle via an esbuild banner, so the runtime
resolves
with **no server or renderer changes**. Locale comes from the execution
context that already flows to the worker.
The catalog key and `generateMessageId` hashing are shared between the
node
extractor and the browser runtime; `<Trans>` text whitespace is
normalized
identically on both sides so multi-line elements resolve.
## Design notes
- Reuses the existing `extract → compile → manifest.translations`
contract and
`generateMessageId`, so component strings flow through the same
machinery as
manifest labels.
- Self-contained in `twenty-sdk` + a shared pure helper; the server is
untouched.
## Scope / follow-ups
- `twenty dev` (watch) does not bake catalogs yet — preview shows source
strings; use `twenty dev:build` (documented). Wiring the watcher is a
follow-up.
- Usage is documented in twenty-docs under **Apps → Translations**
(`developers/extend/apps/translations`).
## Tests
Unit tests for the catalog-key/interpolation helpers, the runtime
resolver
(hit/miss/context/fallback/interpolation), and the ts-morph extractor
(static `t`/`msg`/`<Trans>`, dynamic-skip, dedup, multi-line
whitespace), plus a
compile test for context→messageId. Verified with an adversarial review
pass.
https://claude.ai/code/session_01NiE7o3cd3zCLZarVkJa6UA
---
_Generated by [Claude
Code](https://claude.ai/code/session_01NiE7o3cd3zCLZarVkJa6UA)_
<a
href="https://cubic.dev/pr/twentyhq/twenty/pull/22301?utm_source=github"
rel="nofollow noreferrer noopener" target="_blank">``<img alt="Review
in cubic"
src="https://www.cubic.dev/buttons/review-in-cubic-dark.svg">``</a>
---------
Co-authored-by: github-actions <github-actions@twenty.com>
## What
Adds a new docs page under **Developers → Extend → Apps → Logic**
explaining how to give logic functions key-value storage (to persist
intermediate results, cache data, and share state across runs).
Rather than introducing a dedicated storage primitive, the guide shows
how to achieve this with a small **technical object** ("KV Store") that
has a unique `key` field and a `RAW_JSON` `value` field — queried
through the existing typed `CoreApiClient`.
Closes the documentation part of
[core-team-issues#2427](https://github.com/twentyhq/core-team-issues/issues/2427).
## Contents of the new page
- `defineObject` for the `kvStore` object (`key` + `value`)
- A unique index on `key` (the recommended uniqueness primitive)
- `get` / `set` (upsert) / `del` helpers built on `CoreApiClient`
- A worked example: caching an expensive third-party call with a TTL
- Patterns & tips: namespacing, expiry, what to store,
visibility/permissions, per-record scoping
## Files
- `developers/extend/apps/logic/key-value-store.mdx` — the new page
- `navigation/base-structure.json` — navigation source-of-truth
- `docs.json` + `twenty-shared/.../DocumentationPaths.ts` — regenerated
from base-structure
## Notes
- Documentation only — no code/behavior changes.
- This is a convention (a regular custom object), not a new feature, so
it inherits the same sync, permissions, and tooling as the rest of an
app's data.
https://claude.ai/code/session_01XAgXy1mUUMff5BFkFPjtfZ
---
_Generated by [Claude
Code](https://claude.ai/code/session_01XAgXy1mUUMff5BFkFPjtfZ)_
<!-- This is an auto-generated description by cubic. -->
<a
href="https://cubic.dev/pr/twentyhq/twenty/pull/22061?utm_source=github"
target="_blank" rel="noopener noreferrer"
data-no-image-dialog="true"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://www.cubic.dev/buttons/review-in-cubic-dark.svg"><source
media="(prefers-color-scheme: light)"
srcset="https://www.cubic.dev/buttons/review-in-cubic-light.svg"><img
alt="Review in cubic"
src="https://www.cubic.dev/buttons/review-in-cubic-dark.svg"></picture></a>
<!-- End of auto-generated description by cubic. -->
## Summary
The Getting Started pages on the docs site (docs.twenty.com) were only
ever available in English, never translated into the other supported
languages.
**Root cause:** The Getting Started section (added in #19728) was never
added to the Crowdin source config (`crowdin-docs.yml`), so its `.mdx`
files were never uploaded for translation. Only `user-guide`,
`developers`, and `twenty-ui` were configured.
This also surfaced a related bug: because the pages had no translations,
the navigation generator fell back to the English page path for every
language, duplicating paths like `getting-started/introduction` across
all 14 language navs. Mintlify treats duplicate cross-language paths as
undefined behavior, which broke the language switcher (it always
redirected to `/getting-started/introduction`).
## Changes
- `.github/crowdin-docs.yml` — add `getting-started/**/*.mdx` as a
translation source so the pages get sent to Crowdin.
- `packages/twenty-docs/scripts/fix-translated-links.sh` — add
`getting-started` link-rewriting rules to match the other sections.
- `packages/twenty-docs/scripts/generate-docs-json.ts` — only include a
page in a non-default language when its translated file exists; drop
empty groups/tabs (removes the duplicate cross-language paths that broke
the switcher).
- `packages/twenty-docs/docs.json` — regenerated.
<!-- This is an auto-generated description by cubic. -->
<a
href="https://cubic.dev/pr/twentyhq/twenty/pull/21842?utm_source=github"
target="_blank" rel="noopener noreferrer"
data-no-image-dialog="true"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://www.cubic.dev/buttons/review-in-cubic-dark.svg"><source
media="(prefers-color-scheme: light)"
srcset="https://www.cubic.dev/buttons/review-in-cubic-light.svg"><img
alt="Review in cubic"
src="https://www.cubic.dev/buttons/review-in-cubic-dark.svg"></picture></a>
<!-- End of auto-generated description by cubic. -->
---------
Co-authored-by: Cursor <cursoragent@cursor.com>
## What
Removes the community-maintained **"Other methods"** cloud-providers
page from the self-host docs (it covered Kubernetes/Terraform/Coolify
community deployments).
## Changes
- **Deleted** `developers/self-host/capabilities/cloud-providers.mdx`
and its 13 localized copies (ar, cs, de, es, fr, it, ja, ko, pt, ro, ru,
tr, zh).
- **Removed the slug** from `navigation/base-structure.json` (the source
of truth) and regenerated the derived files via the repo's own
generators (`yarn docs:generate`, `yarn docs:generate-paths`):
- `docs.json` — nav entries dropped for every locale.
- `twenty-shared/.../DocumentationPaths.ts` —
`DEVELOPERS_SELF_HOST_CAPABILITIES_CLOUD_PROVIDERS` constant dropped
(was unused elsewhere).
- **Removed the "Cloud Providers" card** from the `self-host` overview
pages across all locales.
- **Dropped the dangling redirect**
`/developers/self-hosting/cloud-providers` (its destination no longer
exists).
- Cleared the matching entry from the unused `navigation-schema.json`
for consistency.
Net: 68 line deletions across config (pure removal); no insertions.
## Verification
- `grep` confirms **0** remaining references to `cloud-providers`
anywhere in the repo.
- All touched JSON files parse; `oxlint` on twenty-docs reports 0
errors.
- Generators (not hand edits) produced `docs.json` and
`DocumentationPaths.ts`.
> Note: `mintlify broken-links` can't run to completion on this branch
due to a **pre-existing** MDX parse error in the unrelated
`l/ar/.../contribute/contribute.mdx`; the grep above is the equivalent
guarantee that no link points at the removed page.
## Scope & Context
Closes#20358.
The Apps docs were restructured into nested pages, but the generated
docs navigation source still pointed to the old flat Apps page slugs.
This made Developers > Apps navigation entries point to removed English
docs pages.
## Technical inputs
- Update `packages/twenty-docs/navigation/base-structure.json` to use
the current nested Apps docs structure.
- Regenerate `packages/twenty-docs/docs.json` and
`packages/twenty-docs/navigation/navigation.template.json` from the
updated structure.
- Update `generate-docs-json.ts` so localized navigation falls back to
the English slug when the localized `.mdx` file does not exist yet,
avoiding generated 404 links while translations catch up.
## Validation
- Parsed `docs.json`, `base-structure.json`, and
`navigation.template.json` as valid JSON.
- Checked all generated navigation page slugs against existing `.mdx`
files: `missing nav mdx 0`.
- Checked Apps navigation specifically: `missing apps nav mdx 0`.
`yarn docs:generate` could not be run in this local environment because
Yarn/Corepack is not installed here, so I regenerated the JSON files
with the same generator logic via Node.
Co-authored-by: dev111-actor <dev111-actor@users.noreply.github.com>
## Summary
- **New Getting Started section** with quickstart guide and restructured
navigation
- **Halftone-style illustrations** for User Guide and Developer
introduction cards using a Canvas 2D filter script
- **Removed hero images** (`image:` frontmatter + `<Frame><img>` blocks)
from all user-guide article pages
- **Cleaned up translations** (13 languages): removed hero images and
updated introduction cards to use halftone style
- **Cleaned up twenty-ui pages**: removed outdated hero images from
component docs
- **Deleted orphaned images**: `table.png`, `kanban.png`
- **Developer page**: fixed duplicate icon, switched to 3-column layout
## Test plan
- [ ] Verify docs site builds without errors
- [ ] Check User Guide introduction page renders halftone card images in
both light and dark mode
- [ ] Check Developer introduction page renders 3-column layout with
distinct icons
- [ ] Confirm article pages no longer show hero images at the top
- [ ] Spot-check a few translated pages to ensure hero images are
removed
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: github-actions <github-actions@twenty.com>
## Summary
This PR implements OAuth 2.0 Dynamic Client Registration (RFC 7591) and
OAuth 2.0 Protected Resource Metadata (RFC 9728) support, enabling
third-party applications to dynamically register as OAuth clients
without manual configuration.
## Key Changes
### OAuth Dynamic Client Registration
- **New Controller**: `OAuthRegistrationController` at `POST
/oauth/register` endpoint
- Validates client metadata according to RFC 7591 specifications
- Enforces PKCE-only public client model (no client secrets)
- Supports only `authorization_code` grant type and `code` response type
- Rate limits registrations to 10 per hour per IP address
- Returns `client_id` and registration metadata in response
- **Input Validation**: `OAuthRegisterInput` DTO with constraints on:
- Client name (max 256 chars)
- Redirect URIs (max 20, validated for security)
- Grant types, response types, scopes, and auth methods
- Logo and client URIs (max 2048 chars)
- **Discovery Endpoint Update**: Added `registration_endpoint` to OAuth
discovery metadata
### Stale Registration Cleanup
- **Cleanup Service**: Automatically removes OAuth-only registrations
older than 30 days that have no active installations
- **Cron Job**: Runs daily at 02:30 AM UTC with batch processing (100
records per batch)
- **CLI Command**: `cron:stale-registration-cleanup` to manually trigger
cleanup
### MCP (Model Context Protocol) Authentication
- **New Guard**: `McpAuthGuard` implements RFC 9728 compliance
- Wraps JWT authentication with proper error responses
- Returns `WWW-Authenticate` header with protected resource metadata URL
on 401
- Enables OAuth-protected MCP endpoints
### Protected Resource Metadata
- **New Endpoint**: `GET /.well-known/oauth-protected-resource` (RFC
9728)
- Advertises MCP resource as OAuth-protected
- Lists supported scopes and bearer token methods
- Enables OAuth clients to discover authorization requirements
### Application Registration Updates
- **New Source Type**: `OAUTH_ONLY` enum value for OAuth-only
registrations
- **Install Service**: Skips artifact installation for OAuth-only apps
(no code artifacts)
### Frontend Updates
- **Authorization Page**: Support both snake_case (standard OAuth) and
camelCase (legacy) query parameters
- `client_id` / `clientId`
- `code_challenge` / `codeChallenge`
- `redirect_uri` / `redirectUrl`
## Implementation Details
- **Rate Limiting**: Uses token bucket algorithm with 10 registrations
per 3,600,000ms window per IP
- **Scope Validation**: Requested scopes are capped to allowed OAuth
scopes; defaults to all scopes if not specified
- **Redirect URI Validation**: Uses existing `validateRedirectUri`
utility for security
- **Cache Headers**: Registration responses include `Cache-Control:
no-store` and `Pragma: no-cache`
- **Batch Processing**: Cleanup operations process 100 records at a time
to avoid memory issues
- **Grace Period**: 30-day grace period before cleanup to allow time for
client activation
https://claude.ai/code/session_01PxcuWFFRuXMASMaMGTLYk2
---------
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>
Co-authored-by: github-actions <github-actions@twenty.com>
Co-authored-by: cubic-dev-ai[bot] <191113872+cubic-dev-ai[bot]@users.noreply.github.com>
## Summary
- Restructures the developer Extend documentation: moves API and
Webhooks to top-level pages, creates dedicated Apps section with Getting
Started, Building, and Publishing pages
- Updates navigation structure (`docs.json`, `base-structure.json`,
`navigation.template.json`)
- Updates translated docs for all locales and LLMS.md references across
app packages
## Test plan
- [ ] Run `mintlify dev` locally and verify navigation structure
- [ ] Check that all links in the Extend section work correctly
- [ ] Verify translated pages render properly
Made with [Cursor](https://cursor.com)
---------
Co-authored-by: github-actions <github-actions@twenty.com>
## Summary
- **Fix junction relation toggle not being saved**: The form schema
wasn't tracking the `settings` field, so changes to
`junctionTargetFieldId` weren't marked as dirty
- **Add type-safe documentation paths**: Generate TypeScript constants
from `base-structure.json` to prevent broken documentation links
- **Create many-to-many relations documentation**: Step-by-step guide
for building many-to-many relations using junction objects
- **Update `getDocumentationUrl`**: Now uses shared constants from
`twenty-shared` for base URL, default path, and supported languages
## Key Changes
### Junction Toggle Fix
- Added `settings` field to the form schema in
`SettingsDataModelFieldRelationForm.tsx`
- Fixed the toggle to properly merge settings when updating
`junctionTargetFieldId`
### Type-Safe Documentation Paths
- New constants in `twenty-shared/constants`:
- `DOCUMENTATION_PATHS` - All 161 documentation paths as typed constants
- `DOCUMENTATION_SUPPORTED_LANGUAGES` - 14 supported languages
- `DOCUMENTATION_BASE_URL` / `DOCUMENTATION_DEFAULT_PATH`
- Generator script: `yarn docs:generate-paths`
- CI integration: Added to `docs-i18n-pull.yaml` workflow
### Documentation
- New article:
`/user-guide/data-model/how-tos/create-many-to-many-relations`
- Updated `/user-guide/data-model/capabilities/relation-fields.mdx` with
Lab warning and link
## Test plan
- [ ] Verify junction toggle saves correctly when enabled/disabled
- [ ] Verify documentation link opens correct localized page
- [ ] Verify `yarn docs:generate-paths` regenerates paths correctly
- added article to detail how to attach a pdf to a given record
- added link in another article
- updated the english section of the docs.json to have the file appear
in the left menu
- updated the 2 navigation files
---------
Co-authored-by: github-actions <github-actions@twenty.com>
- more details on rate at which messages are imported from Gmail
- Settings -> Release deprecated to Settings -> Updates => this leads to
updating the file title, file name and the navigation files
- Support & Documentation accessible via Settings and no longer the nav
bar
- updated features out of the lab
- no more integration page
- added a new article with step by step on how to notify a teammate of a
note to review
docs.json is updated only for the English part
---------
Co-authored-by: github-actions <github-actions@twenty.com>
Created by Github action
Pulls the latest documentation translations from Crowdin for all
supported languages:
- French (fr)
- Arabic (ar)
- Czech (cs)
- German (de)
- Spanish (es)
- Italian (it)
- Japanese (ja)
- Korean (ko)
- Portuguese (pt)
- Romanian (ro)
- Russian (ru)
- Turkish (tr)
- Chinese (zh-CN)
---------
Co-authored-by: github-actions <github-actions@twenty.com>
## Summary
The merge conflict resolution from PR #16705 incorrectly discarded the
new documentation structure changes. This PR updates the navigation JSON
files (the correct approach) to restore the intended changes.
## Changes restored
- New 'Capabilities' and 'How-Tos' subgroups organization
- Renamed sections (e.g., 'Getting Started' → 'Discover Twenty')
- New sections: Data Migration, Calendar & Emails, AI, Views &
Pipelines, Dashboards, Permissions & Access, Billing
- Reorganized Developers section with Extend, Self-Host, and Contribute
groups
## Files updated
- `navigation/base-structure.json`
- `navigation/navigation-schema.json`
- `navigation/navigation.template.json`
## Context
PR #16705 was merged but the merge conflict was incorrectly resolved,
causing all the structural changes to be lost. The previous fix (PR
#16741) updated docs.json directly, but the correct approach is to
update the navigation JSON files instead. This PR properly restores
those changes from the final commit of PR #16705
(`c856e0d598a0056c2bdaf528502e08261daf7c7c`).
---------
Co-authored-by: github-actions <github-actions@twenty.com>
## Summary
The merge conflict resolution from PR #16705 incorrectly discarded the
new documentation structure changes. This PR restores the intended
changes.
## Changes restored
- New 'Capabilities' and 'How-Tos' subgroups organization
- Renamed sections (e.g., 'Getting Started' → 'Discover Twenty')
- New sections: Data Migration, Calendar & Emails, AI, Views &
Pipelines, Dashboards, Permissions & Access, Billing
- Reorganized Developers section with API subsection
- URL redirects for SEO and user experience continuity
## Context
PR #16705 was merged but the merge conflict was incorrectly resolved,
causing all the structural changes to be lost. This PR brings back those
changes from the final commit of PR #16705
(`c856e0d598a0056c2bdaf528502e08261daf7c7c`).
Félix Malfait
