Skip to main content

Twinit AI Composer (BETA) User Guide

The AI Composer (BETA) is a beta feature. Work completed using the BETA version will be supported in the final version. Documentation is still being updated. You may see old references to Cursor in the AI Composer documentation and IDEExtension user interface, however both Cursor and Visual Studio Code are supported in the BETA release.

AI is imperfect and can make mistakes. All code generated with the use of the AI Composer (BETA) is generated using a third-party AI of your choosing not by Twinit or any of its services. By continuing to use the AI Composer (BETA) feature you agree to the understanding that mistakes can be made by the agent you choose to generate code. Twinit highly recommends all generated code goes through a review process before being used in production.

The AI Composer (BETA) helps you build Twinit applications with an AI coding agent. It gives the agent the knowledge it needs to work with Twinit, so the agent builds your app the way Twinit expects. That covers the platform services, the item data model, template packages, OMAPI, sign-in, and the web client. The agent follows Twinit v5.2.

The AI Composer (BETA) ships inside the Twinit IDE Extension. It works with Cursor, and with Claude Code in Cursor or Visual Studio Code. When you add it to a project folder, the extension writes rules, skills, and agents into .cursor or .claude. The coding agent reads them while it works. You describe the app you want. The agent plans it with you, writes the backend and the web client, and deploys the backend template package into the workspace you are signed in to.

The AI Composer (BETA) does not replace you. It writes code quickly, but you are still the owner of that code. Read Recommended hygiene for AI generated code before you put anything it builds in front of users.

Preparing to use the AI Composer (BETA)​

Prepare by opening AI Composer Setup (BETA) and working down its rows. Each row is one part of the setup. A failed row says what is missing, and it often has a button that fixes the problem or opens the right place. Click Refresh after you fix something. When every row passes, start a new chat.

  1. Open the Support Center panel.
  2. Click Twinit Configuration Check.
  3. Click the AI Composer Setup (BETA) tab.

The tab has two columns. Environment & Cursor checks this window and the open folder. Twinit Project checks one workspace you pick from a list. Work the rows in the order below. The project column asks you to sign in until this window has a session.

A project folder is open​

This row fails until a folder is open in Cursor or Visual Studio Code. Click Open Folder on the row.

For a new app, start with an empty folder. That folder holds both parts of the app:

  • The web client, the pages people open in a browser. For a new Vite app this is a client/ folder.
  • The template package, usually a template-package folder. This is the Twinit content the agent deploys into the workspace: scripts, user configs, API configs, collections, and the rest. See How the AI Composer (BETA) uses template packages.

DTPLATFORM keys and npm​

The DTPLATFORM keys and npm row fails until npm is installed, the three variables are set from your Production keys, and npm can reach the Twinit registry. Click Configuration Check on the row. That opens the Basic Setup tab of Twinit Configuration Check. Use Create NPM Environment Variables. The view writes DTPLATFORM_SECRET_BASE64 for you from the secret key. Restart the editor after saving so new terminals see the variables, then click Refresh. A passing row has Review.

The web client installs Twinit packages from the private npm registry at npm.twinit.dev. That registry accepts Production user access keys. Create those keys on your Production account, even when the app itself is built on Sandbox. It is likely that you may have already created these environment variables if you have completed Twinit Academy.

The extension reads three environment variables:

VariableWhat it holds
DTPLATFORM_KEYYour Production user access key
DTPLATFORM_SECRET_BASE64Your Production secret key, encoded as Base64
DTPLATFORM_EMAILThe email address you use to sign in to Twinit

These keys stay in your user environment. They do not go in the project folder. The agent pins @dtplatform/platform-api to the 5.2 line (~5.2.0). A caret range would accept later 5.x versions this knowledge has not been checked against.

Signed in​

The Signed in row fails until this window has a Twinit session. Click Sign In on the row.

You need a Twinit account on the environment where you are building the app. For most development that environment is Twinit Sandbox.

In the Projects, Scripts & Configs panel, open the top-right menu and choose Signin. Pick the Sandbox environment, or whichever environment holds the application you are developing. Stay signed in to that environment while you build. The agent deploys into the workspace on the environment you are signed in to. Click Refresh on the setup tab when you are back.

AI Composer (BETA)​

The AI Composer (BETA) row fails until the open folder has the AI Composer (BETA) at the same knowledge version as this extension. Click Add Context if it is missing, Update Context if it is older, or Replace if the record cannot be read. A folder that is newer than this extension still passes, with a note to update the extension. Click Refresh after you add or update it.

Add the AI Composer (BETA) to a folder​

  1. Open the folder for your app in Cursor or Visual Studio Code.
  2. In the Projects, Scripts & Configs panel, open the top-right menu and choose BETA: Add AI Composer to Your Project. The AI Composer (BETA) commands are near the top of the menu, just below Signin.
  3. Choose Continue on the notice about reviewing generated code.
  4. Pick the folder. The dialog title is Select the application folder to add AI Composer (BETA) to. The extension remembers it and suggests it next time.
  5. Pick the AI coding tool, Cursor or Claude Code. The list leads with the tool the folder is already set up for. A .cursor folder means Cursor. A .claude folder or a CLAUDE.md file means Claude Code. If neither is there, Cursor is first when the extension is running in Cursor, and Claude Code is first otherwise. Press Enter to accept the first choice.
  6. Pick the client framework, Vite or ipa-core. See Choosing Vite or ipa-core.

The extension writes the rules, skills, and agents into .cursor or .claude, depending on the tool. It also writes .twinit-agent-context.json at the root of the folder. That file records the knowledge version, the framework, the tool, and a fingerprint of each file it wrote. The fingerprints let a later update tell which files you have changed. Do not delete this file.

ToolFolderRules
Cursor.cursor.cursor/rules/*.mdc
Claude Code.claude.claude/rules/*.md

Skills and agents use the same layout under either folder. Claude Code does not get a generated CLAUDE.md. A CLAUDE.md you already have is left as it is.

The extension also writes a small launcher at .cursor/twinit/twinit-tmp-pkg.cjs or .claude/twinit/twinit-tmp-pkg.cjs. The agent uses it to check and deploy template packages. The launcher points at files on your computer, so that twinit folder has its own .gitignore and stays out of source control.

The installed skills include workflows you can start by name, such as /plan-twinit-app and /create-twinit-app. You do not have to use them. Describing the app in your own words is enough. The installed agents are twinit-app-planner, twinit-app-builder, twinit-backend-configurator, twinit-ui-developer, and twinit-template-reviewer. The coding tool can hand work to them. You still talk to one chat.

Choosing Vite or ipa-core​

When you add the AI Composer (BETA), you pick the framework for your app's web client. It installs only the knowledge for the framework you pick, so the agent does not mix the two up. Both are valid choices. They suit different apps.

Vite builds a plain React app with Vite. You decide every page, route, and component. New applications receive this choice. The picker labels it Vite (recommended for new applications).

  • The client calls your API endpoints directly. There are no handler scripts in between.
  • Routes are written in the client's code, not in user configs. Do not model pages as user configs.
  • The client lives in a client/ folder. The AI Composer (BETA) brings working files for sign-in, the API client, and session setup. On a new app the agent copies those files in, so those parts are right from the start.
  • You build the layout, navigation, and project selection yourself, or the agent builds them for you.
  • The copied dev server uses http://localhost:8088/. The port must match a redirect registered on your application. See Application redirects.

Choose Vite when you are starting a new app, or when you want full control of the look and behavior of the client.

ipa-core builds the app on IPA Core v3.0, the Twinit UI framework documented on twinit.dev. The picker describes it as IPA Core v3.0. Use when maintaining an ipa-core application. The client starts from npx create-twinit-app.

  • The framework handles sign-in, project and user group selection, and the main layout for you.
  • User configs define the pages, navigation, and handlers. The configs live in your Twinit project, so the app's pages are part of what you deploy.
  • Built-in pages are ready to use: dashboards, entity views, file uploads, downloads, the script runner, OMAPI, and user group management. The 3D viewer is supported too.
  • Your own pages go in app/ipaCore/pageComponents.
  • Pages get data from thin handler scripts that call your API endpoints.
  • Local sign-in uses http://localhost:8084.

Choose ipa-core when you are maintaining an ipa-core application, or when the built-in pages cover much of what the app needs.

The agent's guidance treats a new app as Vite. If you chose ipa-core on purpose for a new app, tell the agent so at the start of the chat.

To change frameworks later, run BETA: Add AI Composer to Your Project again, choose Replace, and pick the other framework. To change tools, do the same and pick the other tool. See what Replace removes in the next section. An update never changes the tool. If the folder later looks like the other framework, the update asks before it switches. See Run the update.

Adding the AI Composer (BETA) to an existing project​

You can add the AI Composer (BETA) to an app that was built without it.

Before you start:

  • Commit your work, or create a new branch, so you can see and undo everything the agent changes.
  • The first install does not delete .cursor or .claude. It writes the AI Composer (BETA) files into the folder for the tool you pick. If a file it needs to write is already there, it lists those files and asks you to Replace them. Their contents are replaced, and that cannot be undone. Everything else in that folder stays, including rules, skills, and agents your team wrote. Copy anything you might want back before you confirm. Later updates never delete your own files. See Handling new updates to the AI Composer (BETA).

Then:

  1. Open the project folder and run BETA: Add AI Composer to Your Project.
  2. Choose the tool. If the folder already has .cursor, or .claude or CLAUDE.md, that tool is listed first.
  3. The extension looks at the folder to work out the framework. A vite.config file means Vite. An app/ipaCore folder means ipa-core. It puts that choice first. Accept it unless you know it is wrong.
  4. Start a new chat or session. Before you ask for changes, ask the agent to read the project and describe what it finds: the client, the backend scripts and API configs, and any template package. Then describe the change you want, or point it at a spec.

The agent is told not to overwrite an existing client. It checks your sign-in, API client, and session code against what the AI Composer (BETA) expects. If something is missing, it patches only that one thing and explains why. It does not replace whole files. Check its changes in your source control anyway.

If your project has no template package yet, ask the agent to create one from what is already in your Twinit project. From then on, the package is the true copy of your backend. See How the AI Composer (BETA) uses template packages.

If you run BETA: Add AI Composer to Your Project on a folder that already has the AI Composer (BETA), it asks whether to Update or Replace. Choose Update in almost every case. It runs the same review as BETA: Update AI Composer in Your Project, so your own files and edits are safe.

Replace removes the installed AI Composer (BETA) and installs it again. You pick the tool and the framework again. Confirm with Delete and Install. Deleted files go to the trash where your system supports it.

  • For Cursor, Replace deletes the whole .cursor folder, including rules, skills, and agents you added. The extension tells you how many files will go.
  • For Claude Code, Replace deletes only the files the AI Composer (BETA) installed. Your settings, worktrees, and any rules, skills, or agents you added stay. Edits you made to the installed files are lost.

A record the extension cannot read is treated as a Cursor install, so Replace clears .cursor.

The Application Developers group​

The Application Developers group row checks the application you are signed in to. Click Open Console on the row if you are not a member.

You must be a member of the Application Developers user group for that application.

That group is what makes you a developer of the application. Membership lets you create workspaces in the application, which is where the app's Twinit content lives, and it grants the other permissions a developer needs to build and deploy that content.

If you are not in the group, ask the Application Owner to invite you. The owner adds you in Twinit Console. You cannot create a workspace for the application until that invitation is accepted.

Application redirects​

The Application redirects row fails until the signed-in application lists a local sign-in address. Click Open Console on the row to add one.

Local sign-in sends the browser back to your computer. The address depends on the web client you picked when you added the AI Composer (BETA). See Choosing Vite or ipa-core.

Web clientRedirect the setup check looks for
Vitehttp://localhost:8088/ — the trailing slash is required
ipa-corehttp://localhost:8084

An application owner adds the redirect in Twinit Console. Add the one that matches the client you will build, or both if unknown.

The Vite files the agent copies listen on port 8088 and refuse to start if that port is taken, so sign-in cannot silently move to another port. This row passes when the application lists http://localhost:8088/ or http://localhost:8084. If your application already uses a different local port, register that exact address as well and tell the agent which port to use. The row still looks only for the two addresses in the table. Click Refresh after the redirect is saved.

Without a matching redirect, the client can run locally and still fail at sign-in.

Select a Twinit project​

The Twinit Project column lists the workspaces in the application you are signed in to. The Select a Twinit project row fails until you pick one. Click New Project on the row if the list is empty.

You need a workspace in the application to develop in. The extension lists these workspaces as projects. Create one from the extension panel menu with New Project, or use a workspace that already exists for this work. The agent deploys the template package into this workspace.

After you pick a project, the row becomes Selected project and shows the project name, its namespace, and the MCP server name the next row expects.

Twinit MCP for this project​

The Twinit MCP for this project row fails until Cursor has an MCP server for the project you picked. The row reads ~/.cursor/mcp.json only. It matches a server to the project by the project's namespace on the server URL. When that URL has no namespace, it matches the expected server name instead, twinit- plus a slug of the project name.

Note: This MCP check only works for Cursor at the moment. It does not check Claude Code's MCP configuration. If you use Claude Code, this row can stay failed even when MCP is set up correctly. Confirm the Twinit server with /mcp in Claude Code instead.

MCP lets the agent read the live workspace, so it can check that a deploy created the collections, scripts, and API routes it expected. MCP access is read only. The agent cannot change the workspace through it.

  1. Open the AI Service panel.
  2. Right-click the workspace and choose Configure MCP.
  3. Enter an API key and secret. The panel links to the account page where you create them. These keys belong to your account on the development environment. They are separate from the DTPLATFORM_* variables.
  4. Leave the selected MCP tools as they are. All services are enabled by default, which is what the agent needs to check a deploy.
  5. Install the config for the tool you chose.

Cursor. Click Add to Cursor MCP. Approve the install in the Cursor settings dialog. If the MCP tools do not load, restart Cursor.

Claude Code. Click Copy to Clipboard. The copied config has one entry under mcpServers. In a terminal, add that entry as a user-scoped server. Use the entry's name and its JSON object:

claude mcp add-json --scope user <server-name> '<entry JSON>'

Run this yourself. The entry holds your credentials, so it must not go in the project's .mcp.json, which is usually committed. Start a new Claude Code session. /mcp lists the connected servers. Click Refresh. For Cursor, the Twinit MCP for this project row should pass.

Start a chat that uses the AI Composer (BETA)​

When every row passes, start a new Cursor chat or a new Claude Code session. A chat or session that was already open does not pick up the new files. Tell the agent what to build there.

Using the AI Composer (BETA)​

Start a new chat​

Cursor

  1. Open the project folder in Cursor.
  2. Start a new chat. Use the new-chat control in the chat panel. A chat that was already open does not see the AI Composer (BETA) files.
  3. If this window has more than one folder open, right-click the .cursor folder and choose Add Directory to New Cursor Chat. That attaches the right folder to the chat. With one folder open, a new chat is enough.

Claude Code

  1. Open the project folder in Claude Code.
  2. Start a new session. A session that was already open does not see the files in .claude.
  3. After the Twinit MCP for this project row, run /mcp and confirm the Twinit server is listed.

Stay in that chat or session while the agent plans and builds. Start another one when you come back later, or after you update the AI Composer (BETA).

Tell the agent what to build​

In the new chat, describe the app in your own words, or give it a specification you already have. You do not need a special command. /plan-twinit-app starts the same planning step if you prefer to name it.

Functional requirements. Write what people do with the app, who they are, and what data they work with. A short list is enough. For example:

Build a Twinit app for facility managers.

- A manager signs in and picks a building.
- They record an inspection: date, area, pass or fail, and notes.
- They can look up past inspections for that building.
- The app name is Site Inspections. Use a dark header and our blue, #1B4F8A.

A specification. If you already have a spec, put the file in the project folder and tell the agent where it is. You can also attach the file to the message.

Build this Twinit app from the specification in docs/inspection-spec.md.
Ask me about anything the spec does not cover before you write code.

Say which client you chose if it is ipa-core. The agent otherwise treats a new app as Vite. See Choosing Vite or ipa-core.

For an app that already exists, first ask the agent to read the project and describe what it finds. Then describe the change, or point it at a spec for that change. See Adding the AI Composer (BETA) to an existing project.

Review the plan​

The agent asks about anything it still needs:

  • What the app is for, and who uses it
  • What data it stores, and how that data relates. A sensor, or anything that will have readings over time, is a telemetry item, not an ordinary item with a related feed.
  • Which operations the app performs. Each becomes an API endpoint.
  • What the pages look like
  • Theming and branding: the app name, logo, colors, and header and navigation
  • Whether this is a new Vite app or an existing ipa-core app

It writes the plan to docs/<app-name>-plan.md and asks you to approve it or change it. It does not write code until you approve. Read the plan. Fixing a wrong idea there is much easier than fixing it in the code.

Reply in the same chat. Say what to change, or say the plan is approved and to build it.

The agent builds the app​

After you approve the plan, the agent builds the app in phases. It finishes each phase and checks it before it starts the next:

  1. Sign-in, one Admin user group, and a separate all-access Permission record for that group. Ordinary users are not added yet.
  2. API endpoints (OMAPI) and the scripts that hold your business logic
  3. User groups and user configs. A Vite app does not put its pages in user configs. An ipa-core app does.
  4. Setup scripts and workflows. New apps use the Workflow Service for imports and scheduled jobs. They do not use the Datasources service.
  5. AI agents and teams, if your app needs them
  6. Collections, the items and relationships in them, and telemetry collections when the app has sensors
  7. Files and graphics, if your app needs them
  8. Notifications, if your app needs them
  9. The template package
  10. The web client, in client/ for Vite
  11. Deploying and checking the result

The agent starts the web client's development server in the background and tells you its address. Open the address in your browser to watch the app take shape while the agent works. If you stop the server, the agent leaves it stopped and asks before starting it again.

The agent asks you for values it should not guess. These include the Twinit environment, the application ID, the project, and the development server port. Answer them. Do not let the agent pick on its own, especially the environment. Picking the wrong environment can deploy into someone's live project.

Later changes use the same chat, or a new one. Describe the change the same way: what should be different, or a spec for that change. For example, "Add a page where a manager can close an inspection" or "Apply the changes in docs/close-inspection.md".

How the AI Composer (BETA) uses template packages​

A Twinit app has two parts. The Twinit content lives in your Twinit project: scripts, user configs, API configs, collections, items, user groups, and files. The web client is the pages people open in a browser.

The AI Composer (BETA) always puts your Twinit content in a template package. This is a folder in your project, usually template-package/. Its manifest.json lists what to create and in what order. Because the whole backend is in files, you can review it, keep it in source control, and deploy the same setup to a new project.

A new package looks like this:

my-twinit-app/
├── client/ # Vite + React app. An ipa-core app uses its own layout instead.
├── template-package/
│ ├── manifest.json
│ ├── scripts/
│ ├── configs/
│ ├── omapiConfig/
│ └── workflows/ # only when the app has pipelines or scheduled jobs
└── docs/
└── <app-name>-plan.md

The manifest deploys, in this order: an initialize script, scripts, user configs, API configs, file uploads and file-linked knowledge bases, custom MCP tools, AI agents and teams, workflows, user groups and their links to user configs, collections, and the items in them. A setup script runs last. That script is where the Admin group's separate Permission record is created, and anything else the manifest cannot deploy. A new package has no orchestrators entries. The manifest still accepts them, and the agent is told not to add them.

Each kind of resource has its own rule for what happens when it already exists in the project. A script or user config gets a new version. A workflow is left alone unless the manifest says to recreate it. You do not need to learn these rules. The agent sets them, and the validator rejects a value that does not apply. They do explain why deploying the same package twice is safe.

The agent does not create things in your Twinit project one at a time. It changes the template package and deploys the whole package.

Validate after every change. After each change to the package, the agent runs the template package launcher that the AI Composer (BETA) installed. The path is .cursor/twinit/twinit-tmp-pkg.cjs for Cursor and .claude/twinit/twinit-tmp-pkg.cjs for Claude Code:

node .cursor/twinit/twinit-tmp-pkg.cjs validate ./template-package

Validation runs on your computer. It needs no network and no keys. It reports one problem at a time, so the agent fixes the problem and runs it again until the package is valid. The agent does not zip the package itself. The tool does that.

Deploy after you agree. Before the first deploy in a chat, the agent tells you which project and environment it will deploy to, and waits for you to agree. After that it can deploy again as it works. It asks again if the project or environment changes.

node .cursor/twinit/twinit-tmp-pkg.cjs deploy ./template-package

Use .claude/twinit/twinit-tmp-pkg.cjs in that command when the project was installed for Claude Code.

The deploy uses your sign-in to the Twinit IDE Extension. You do not give the agent any keys. The project name goes in twinit.config.json at the root of your folder. That file holds no secrets, so commit it. If twinit.config.json names a different environment from the one you are signed in to, the tool refuses to deploy. Sign in to the right environment, or fix the file. Do not let the agent force its way past the warning.

Check the result. A successful deploy does not prove everything works. The agent uses MCP to check that the collections, scripts, and routes it expected are in your project. If MCP is not set up, it should say so rather than claim it checked. You can confirm the same resources in the extension's service trees.

You can always deploy the package yourself. Right-click the project and choose Deploy Template to Project. The result is the same.

The package deploys your Twinit content only. Publish the web client with Client Deploy in the Support Center panel. Client Deploy uploads a built client to Twinit-hosted infrastructure for the application you are signed in to. Access is approved per environment.

Handling new updates to the AI Composer (BETA)​

The AI Composer (BETA) knowledge gets better over time. New versions arrive with updates to the Twinit IDE Extension. Each project keeps the version it was installed with until you update it. That version number is the knowledge version in the extension, separate from the extension's own version.

Updates keep your own work​

Updating is interactive. It does not overwrite your work:

  • Your own rules, skills, and agents are never touched. Files you added under .cursor or .claude stay as they are. The one exception is a new AI Composer (BETA) file with exactly the same path as one of yours. Then the update asks you first. Claude Code's own settings and worktrees in .claude are never part of the update.
  • Your edits to AI Composer (BETA) files are never overwritten without asking. If you changed one of the files it installed, the update shows you the difference and lets you keep your version.
  • Files you have not touched are updated for you. You see the list, but you do not have to decide each one.

The update can tell these cases apart because of .twinit-agent-context.json. When the extension installs or updates a file, it records a fingerprint of the content. On the next update it compares three things for each file: the fingerprint it recorded, the file in your folder now, and the file in the new version. A file whose content still matches its fingerprint has not been touched, so it can be updated safely. A file that does not match has been edited, so you choose. A file with no fingerprint is yours.

Customize without fighting updates​

You can change how the agent works by editing the AI Composer (BETA) files. Usually it is better to add your own.

  • Add new files for your team's conventions. For example, add .cursor/rules/acme-conventions.mdc or .claude/rules/acme-conventions.md, or a skill under .cursor/skills/acme-reporting/ or .claude/skills/acme-reporting/. Give them a name the AI Composer (BETA) will not use, such as your company or team name, and updates never ask about them.
  • Edit an AI Composer (BETA) file only when you need to change what it says. That works, but each update asks you to choose between your version and the new one, and you have to merge any new fixes yourself.
  • Commit the installed folder and .twinit-agent-context.json. That folder is .cursor or .claude, whichever you installed. The record lets every teammate's update tell the AI Composer (BETA) files from your team's files. The twinit folder inside it is ignored by its own .gitignore, because it holds a path that only works on your computer.

Know when an update is available​

Open the AI Composer Setup (BETA) tab in Twinit Configuration Check. If your folder's knowledge version is older than the extension's, the AI Composer (BETA) check fails, shows both version numbers, and has an Update Context button.

Also update after you update the extension, even if the knowledge version has not changed. The template package launcher in .cursor/twinit or .claude/twinit points at the extension's install folder, and that folder changes with each extension update. Every update rewrites the launcher. If the agent reports cannot find module for twinit-tmp-pkg.cjs, run the update.

Run the update​

  1. In the Projects, Scripts & Configs panel, open the top-right menu and choose BETA: Update AI Composer in Your Project.
  2. Choose Continue on the same notice shown when you add the AI Composer (BETA).
  3. Pick the project folder. The extension suggests the last folder you used.

Before it shows you anything, the update checks the folder:

  • If the folder has no .twinit-agent-context.json, the AI Composer (BETA) was never added. Use BETA: Add AI Composer to Your Project instead.
  • If the record cannot be read, use BETA: Add AI Composer to Your Project and choose Replace.
  • If the folder has a newer knowledge version than your extension, a teammate probably updated it with a newer extension. Update your extension first. The update never moves a folder back to an older version.
  • If the folder now looks like the other framework, the update asks first. Continue with keeps the framework you installed. Switch to rebuilds the AI Composer (BETA) for the framework it found. It still asks before it replaces any file you changed.
  • The update never changes the tool. A record written before Claude Code support is a Cursor install. To switch tools, use BETA: Add AI Composer to Your Project and choose Replace.

If nothing has changed, you see a message that the AI Composer (BETA) is already up to date, and the launcher is refreshed. Otherwise a review opens. Its title is Update AI Composer (BETA). The first line shows the old version, the new version, the framework, and the tool, for example Update AI Composer (BETA) from 2.0.0 to 3.0.0 (vite, Cursor). When the version is already current and only files differ, the line starts with Review AI Composer (BETA).

Read the review​

The review groups files by what will happen to them.

Automatic changes. A collapsed line says how many files will be updated automatically. Expand it to see each file and its action: Replace, Add, or Delete. These files have no local edits. The list is read only.

Files that need a choice. Each of these files has its own buttons. You must pick one for every file before Update works.

SectionWhat happenedYour choices
These files were changedYou edited a file the AI Composer (BETA) installed, or a new file lands on a path you already haveView Diff, then Keep or Update
These files were deletedYou deleted a file the AI Composer (BETA) still includesKeep Deleted or Add Back
These edited files are no longer in AI Composer (BETA)The new version drops a file you had editedKeep or Delete

A file you already had, at a path the new version wants to add, is listed under These files were changed with the note This file was not installed by AI Composer (BETA).

View Diff opens your file next to the new version, so you can see exactly what changes. If you want both, copy the lines you need before you choose Update, or keep your file and merge the new lines in by hand.

What each choice means for the next update:

ChoiceResult nowNext update
Keep an edited fileYour version staysAsks again, so you see each new version
Update an edited fileReplaced with the new version. Your edits are lost.Updated automatically until you edit it again
Keep your own file at a new AI Composer (BETA) pathYour file staysAsks again while the AI Composer (BETA) includes that path
Keep DeletedStays deleted for this updateAsks again
Add BackThe new version is installedUpdated automatically
Keep a file the AI Composer (BETA) droppedYour file stays and becomes yoursNever asked about again
Delete a file the AI Composer (BETA) droppedThe file is removedNever asked about again

Two cases are handled quietly. If you edited a file so that it already matches the new version, it is simply recorded as current. If the AI Composer (BETA) drops a file that you had already deleted, it simply forgets the file.

Apply the update​

Click Update to apply your choices, or Cancel to change nothing. Closing the review also changes nothing.

  • If any files will be deleted, the extension lists them and asks you to confirm with Delete. Deleted files go to the trash where your system supports it. If you cancel the deletion, nothing changes and the review stays open.
  • If files in the project change while the review is open, clicking Update refreshes the review with the new plan instead of applying old choices. Review it again and click Update.
  • The record in .twinit-agent-context.json is written last, only after every file change succeeds. If something fails, the error says the record was not updated, and the next update compares against the old record again.

When it finishes, a message says how many files were written, deleted, and kept.

After the update​

  • Start a new Cursor chat, or a new Claude Code session. Chats and sessions that were already open keep using the old files.
  • Commit the changes to .cursor or .claude and .twinit-agent-context.json together, so your teammates get the same version.
  • If you keep your own versions of AI Composer (BETA) files, read the diff each time. A new version may fix a problem that your copy still has.

AI agents write working code fast. They also make mistakes that look right. Treat everything the AI Composer (BETA) writes as code from a new teammate: helpful, but reviewed before it ships.

Do the review in small pieces. Commit after each phase or feature, and read the diff before you go on. A small diff is easy to review. A whole app at once is not.

Security review for keys and secrets​

The AI Composer (BETA) is told never to handle your keys. Check that it followed that rule.

Never paste keys into the chat. The agent never needs your access keys, secret keys, MCP API keys, or LLM API keys. If it asks for one, say no. Enter keys only in the extension's own forms, such as Twinit Configuration Check, Configure MCP, Upload AI Key, and Manage Secrets.

Check what is in source control. Before each commit, look for secrets in the diff:

  • .env, .env.local, and other .env files with real values must not be committed. Commit only .env.example, which lists the names of the settings and no values. A Vite client keeps VITE_TWINIT_API and VITE_TWINIT_APP_ID in .env.local, and reads them with import.meta.env.
  • twinit.config.json should hold only project, and perhaps environment and appId. These are not secret. It must never hold a key or secret.
  • .npmrc should refer to environment variables, such as ${DTPLATFORM_KEY}. It must not hold the keys themselves.
  • Scripts, user configs, API configs, and the template package must not hold API keys, passwords, or tokens. A third-party key belongs in your project's secrets. Your LLM API key goes in through Upload AI Key.
  • Search the whole project for strings like KEY, SECRET, TOKEN, PASSWORD, and Bearer. A secret scanner, such as gitleaks, does this better and can run before each commit.

If a key reaches source control, even in a commit you later undo, treat it as exposed. Create a new key and delete the old one.

Check who can do what. The AI Composer (BETA) starts each app with one Admin user group and a separate all-access Permission record for that group. That group is for the people who set up the app, not for its users. Membership in Admin does not replace a workflow or script permission profile. Before real users join, create groups that have only the access each role needs, and keep ordinary users out of Admin.

In Cursor, you can also ask for a security review of your changes. It looks for exposed secrets and unsafe code. It does not replace your own review.

Architecture review​

The AI Composer (BETA) follows Twinit's recommended architecture for v5.2. Check that the code really does, because small slips add up.

  • Business logic lives in OMAPI scripts. Rules, checks, queries, and changes to data belong in scripts behind API endpoints. React components only display data and call those endpoints.
  • The client does not call the Item Service directly. Every data call goes through the OMAPI client in a Vite app, or through thin handler scripts in an ipa-core app.
  • Batch work uses workflows. Imports and scheduled jobs use the Workflow Service, deployed from the manifest's workflows list. The package should have no orchestrators entries. New apps do not use the Datasources service.
  • Related items use relationships. Items that belong together are linked with Item Service relationships, not by storing another item's ID in a property.
  • A sensor is a telemetry item. Anything that is a sensor, or that will have readings over time, belongs in a NamedTelemetryCollection. It is not an ordinary item plus a separate telemetry feed.
  • The template package is the true copy of the backend. If someone changes the project by hand, the package no longer matches what is deployed. Put the change in the package and deploy again.
  • The app matches the plan. Compare the app with docs/<app-name>-plan.md. Ask the agent to explain anything it added that is not in the plan.

Before each deploy to a shared project, ask the agent in the chat to review the template package and report anything that would fail validation. For anything that matters, also have a person who knows Twinit review the design.

Testing​

The agent checks its own work as it goes, but its checks are not enough on their own.

  • Validate every package change. Make sure the agent ran the validator after its last change, and that the result was valid.
  • Deploy to a fresh project. Deploy the template package to a new, empty project in Sandbox. If it deploys there without help, it will deploy for your teammates and in other environments.
  • Test on Sandbox before Production. Never test a first deploy on a Production project.
  • Check the backend directly. Run scripts with Run Script with Input. Look at recent API calls with Get Last 15 OMAPI Requests. Look in the service trees to confirm the collections and items exist.
  • Try the app the way a user would. Sign in and sign out. Switch projects. Let a session expire, and check that the app asks you to sign in again rather than showing empty pages. Try bad input.
  • Test as someone who is not an admin. Sign in as a user in an ordinary user group. Check that they can do what their role allows and nothing more.
  • Test the production build. From the client folder, run npm run build, then npm run preview, and use the app before you publish it with Client Deploy. A production build can fail in ways the development server does not show.
  • Review the agent's tests. If you ask the agent to write tests, read them. A test that checks the wrong thing passes every time.