Build your first runnable App with AI

This lesson starts with a truly blank project. You create the project, review the AI changes, choose Home, and perform runtime acceptance. AI creates the first operator Page and its localized text.

When you finish, you will have an App named “Packaging Workstation.” It shows the workstation name, simulation mode, current status, and package count, but it does not control any equipment.

What you will accomplish

• Create a blank project in App Hub
• Ask AI to create and validate the first .qp Page
• Understand exactly which resources AI changed
• Set the Page as Home yourself
• Accept it progressively in Design, Preview, and the complete runtime

Three concepts are enough for now

Concept	What you need to know now
App	An independent Theseus project containing Pages, Components, Objects, QG, and configuration.
Page	An operator-facing HMI screen stored as a .qp file.
Component	A visible Page element such as a title, status label, number, or button. A reusable App visual Component uses .qpc.

AI Command Center can modify only the App bound to the current editor window. It cannot create, import, or open projects in App Hub.

Before you start

• Use Theseus Desktop. The runtime page is for using an App that has already been delivered; it does not provide project creation or AI project editing.
• Make sure the AI input can select a model. If no model is available, complete AI provider setup.
• Prepare a parent directory for the project. It may already contain other files.

Step 1: Create Packaging Workstation

1. Select New project in App Hub.
2. Enter Packaging Workstation under App Name.
3. Under Create in, select the project parent directory. Theseus creates a Packaging Workstation child directory there.
4. Leave every option under Modules unchecked.
5. Select Create project. Theseus opens an editor window bound to the new *.the file.

A blank project contains only the base project files. An empty Resources → Pages section is expected.

Step 2: Give AI a bounded task

Select the AI icon in the title bar, or press Cmd+I on macOS or Ctrl+I on Windows and Linux. Start a conversation, type @, select qxqp, and send:

Goal: Create the first runnable operator Home Page for the current Packaging Workstation App.

Page content:
- The title “Packaging Workstation”
- A clearly visible “Simulation mode” label
- A “Not started” status
- A package count of 0
- A clear, restrained layout that operators can scan quickly

Scope:
- Add pages/packaging-station.qp
- Add visible Page text to the current App's i18n.json
- Do not change project settings, Objects, Variables, QG programs, a C# Provider, external equipment, Pulsar, or Safety

Requirements:
- Use native elements/Components supported by the current editor and keep the structure inspectable in Properties
- Do not create physical-equipment actions or a button that appears to start real equipment
- Validate the Page and i18n.json when finished
- Report the changed files, main Components, and validation result

This instruction states the goal, scope, exclusions, and acceptance evidence. Use the same structure for future engineering tasks.

Expected file changes

Before sending the task, note the changes already present in Git or Task details. Task details shows the entire current workspace, not a change list owned exclusively by this AI task.

This lesson is expected to change:

• pages/packaging-station.qp
• i18n.json

AI may read other project information to understand the App. Compare the final file list with the baseline you recorded before the task.

If you see changes to Objects, QG, a C# Provider, Pulsar, or another equipment configuration, do not run the App. Ask AI to explain their origin. Revert an item only after confirming that this task created it and that it is out of scope. Preserve pre-existing, unknown, and other people's changes.

Step 3: Review the result in the editor

After AI saves files, Resources updates:

1. Confirm that packaging-station appears under Resources → Pages.
2. Open the Page, select Design, and check the title, simulation mode, status, and count.
3. Select a Component and confirm that Properties shows understandable ID, content, and layout fields.
4. Switch to Source and confirm that the current document has no inline diagnostic.
5. If the Page uses i18n, open Settings → I18n and check the Chinese and English text needed by this tutorial.
6. Compare the changed-file list, main Components, and validation result in AI's final response with the editor.

AI's explicit Validate result stays in the conversation, while live document diagnostics appear as editor markers. Problems shows only diagnostics produced from the saved project by the latest Build, and saving the project again clears the old Build result. An empty Problems panel before Build is therefore not a complete validation result.

If you had already opened and edited the same Page before AI changed it, the editor keeps the dirty draft and reports a disk conflict. Decide which version to keep before overwriting either one.

Your decision: Set the Page as Home

1. Right-click packaging-station under Resources → Pages.
2. Select Set as Home Page.
3. Confirm that the Home marker appears beside the Page.

Home controls which Page the Runtime target root and Player enter. Theseus does not guess the first Page when Home is not configured.

Step 4: Accept the App progressively

4.1 Build and inspect Problems

1. Save every file and confirm that the App is Stopped.
2. Select Build in the title bar and wait for Build and Deploy to succeed.
3. Open Problems and confirm that this Build reports no Page or i18n error.

Editor Build uses only saved project content and delivers the complete version to the current Runtime target. It does not Start the App.

4.2 Preview inside the editor

Return to packaging-station and select Preview. Confirm that the title, simulation mode, Not started status, and count 0 are visible.

Preview uses the version already deployed to the current target. It can enter Previewing from Stopped on demand or reuse the same App already Previewing, but it does not reuse Running / Debugging, Build, Deploy, or enter the lifecycle. Preview is editor-side verification, not the complete runtime terminal.

4.3 Start and open the complete runtime page

1. Select Start in the title bar and wait for Running.
2. Open the current Runtime target's root address in a browser. The local default is http://127.0.0.1:9210/.
3. If prompted, sign in to the Runtime target first. If the Page requires a business role, sign in separately as an App user.
4. Refresh and confirm that the runtime still returns to the packaging-station Home Page.

The complete runtime page uses only the version already delivered to the current target. If the App is not running, a target Admin confirms the site conditions and performs Start. The runtime page does not read project source, Build, or Deploy.

Why does Start or Debug sometimes require Build?

When the current App and target lack a suitable Build, Start or Debug displays Build and deploy this App? instead of silently building. Build and continue Builds and Deploys first, then automatically retries the requested action. Cancel neither Builds nor continues. Debug always requires a Debug Build.

Acceptance checklist

• AI's file changes match the approved scope
• Design, Properties, and Source review passes
• The Page is saved and selected as Home
• Build succeeds and Problems has no project error from this Build
• Preview is correct and contains no real-equipment action
• The App reaches Running
• The current Runtime target root opens the same Home Page
• Refreshing the complete runtime page succeeds

Safety boundary

warning

This lesson creates a static simulation Page only. Do not replace “Not started” with real equipment status, and do not let AI guess external-controller addresses, axes, I/O, cameras, or interlock meaning. Engineers must define equipment identity and process semantics before Object and QG design begins.

A Page that looks correct does not prove equipment logic is correct. Before running, verify that AI did not add a hidden action or out-of-scope file.

Recovery guide

Symptom	Recovery
No model is available	Open AI provider settings, complete authentication, or refresh the model list.
The Page does not appear in Resources	Check whether the file exists in Files. Resolve any dirty conflict before reopening it.
The Page has an inline error	Mention pages/packaging-station.qp with @ and ask AI to fix only the current diagnostic without adding features.
Preview reports that Build is required	Save, confirm Stopped, and Build. Preview never Builds or Deploys by itself.
Start displays Build and deploy this App?	Review the target, saved files, and Build profile, then select Build and continue; or cancel and Build manually.
The Runtime root says no Home Page is configured	Set the target Page as Home in Resources, then Build and Deploy again.
The complete runtime still shows old content	Save the Page, Stop, Build again, and Start. Refreshing the browser does not deploy source.
AI appears to have changed an Object, QG, or C# Provider	Do not Start. Compare with the pre-task baseline, ask AI to explain, and revert only an out-of-scope change confirmed to come from this task.

Next

The next lesson adds Page state, buttons, and events and asks you to make one change yourself: Page state, buttons, and events.