[Enhancement] Suggestion for improved documentation for new users

[brian-compass]

Problem

As a new user, I've recently started exploring this project and found myself spending a significant amount of time trying to understand how to get started and utilize its features effectively. While there's existing documentation, I believe there's an opportunity to enhance its clarity and comprehensiveness, especially for those who are new to the project.

Specifically, here has been my experience:

• Initial Setup/Installation: Excellent, no problems.
• Basic Scenario Building: Even very basic scenarios have been problematic (using gpt-4o-mini I could not get it to open an app, swapping to gpt-4o is better). I have a very basic flow that involves entering some information into a form and could not get it to work, but this seems like a common scenario.

Proposed Solution

• Basic Usage Examples: Providing more diverse and slightly more complex "getting started" examples (beyond the absolute basics) that demonstrate common use cases would be beneficial. I appreciate that there is a starter project, but perhaps a list of prompts for certain common workflows would be good? Or some more information about how one might integrate MCP into the flow?
• Expanded Examples: Incorporate more practical examples that showcase various functionalities and common workflows. These examples could be categorized by feature or use case?
• FAQ/Troubleshooting Section: This could be populated over time based on recurring questions in issues or discussions. A section addressing frequently encountered problems and their solutions could save new users a lot of time and frustration. For example, I could not get the Agent to enter information into a form (could not recognize the keyboard). If anyone else had encountered this problem I would have loved to see their experience.

Thanks for all your hard work on the project.

[takahirom]

GPT-4.1 is better to run. I'll write it up.
As for samples, I understand, but finding good apps to test is a little difficult.

[brian-compass]

Mastadon is a nice fully-featured app that is sometimes used as an example app in SwiftUI development.

In terms of what other people in the space are doing in terms of documentation, take a look at how Momentic does their docs for 1) finding elements and 2) writing goals

[takahirom]

Thanks. Do you know any way to install it on a simulator?

[takahirom]

We might need to build and save the .app file and run xcrun simctl install booted xxx.app

[brian-compass]

Here is the setup instructions. You basically have to DL the project's raw source code and open the .xcodeproj file. Then press play in XCode, and 🎉 it will install to your selected simulator.

[takahirom]

Thank you for providing a procedure. While we could create a sample, ideally I would prefer to have the tests run directly in the CI environment.

[brian-compass]

Ah, if you want the Mastadon app file (.ipa file) then DL the source code and archive it. It's licensed under GPL-3, which means the source code is free to use.

You should definitely be able to run it in your own CI environment.

[takahirom]

Thanks for the suggestion. I believe that if we can use apps under the Apache or MIT license, it would be better for avoiding potential issues. However, I'm also unsure how we would download the IPA files.
I don't think building the apps ourselves is a good approach, as the maintenance costs could be high, especially considering we might have other apps to manage in the future.