Project context
One paragraph plus the production URL. The sentence "there is no separate mobile codebase" stops Codex from proposing React Native, Capacitor or a second repository when you ask for a mobile feature.
How Codex uses AGENTS.md
Codex looks for AGENTS.md in the repository root (and in subfolders, for folder-specific instructions) and treats its contents as standing instructions for the session: conventions, commands, things to avoid. It is the Codex counterpart of a CLAUDE.md file or Cursor project rules, and it is plain Markdown, so you can keep one source of truth and copy it into the other formats.
For a WebViewGold app the file earns its keep because an agent's defaults are wrong in three specific ways. It assumes a browser, so it reaches for the Web Share API or a PWA manifest where a native call exists. It does not know the bridge syntax, so it invents something like window.WebViewGold.share(). And it has no idea that a Stripe button for credits is a rejection on iOS. The template below fixes all three.
The template
Save it as AGENTS.md in the repository root, replace the bracketed placeholders, and delete the bridge calls you do not use. Every scheme in the table is taken from the WebViewGold iOS docs and Android docs.
markdown
# AGENTS.md - [App name]
## What this project is
[One paragraph: what the app does, who uses it, main stack, e.g. Next.js + Supabase.]
Production URL: https://app.example.com
The same web app is published as native iOS and Android apps with WebViewGold.
The native apps load the production URL inside a WebView (WKWebView on iOS,
Android WebView on Android). There is no separate mobile codebase.
## Runtime context you must respect
- The page can run in three places: desktop browser, mobile browser, native app.
- The native app sends the user agent marker `MYAPPNATIVE` (set in Config.swift
and Config.java). Detect it only through `isNativeApp()` in `src/lib/platform.ts`.
- OAuth popups do not behave like in a browser. Google/Facebook login is handled by
the wrapper (Social Login Helper); Sign in with Apple is handled automatically.
Do not add workarounds that open OAuth in new windows.
- window.open and target="_blank" are governed by the wrapper's URL handling rules.
Use normal links for internal navigation.
- When `isNativeApp()` is true: no "Add to home screen" or "Download our app"
banners, no service worker install prompts, no cookie banner unless legally required.
## WebViewGold JavaScript bridge
Native features are triggered by navigating to a URL scheme:
`window.location.href = "scheme://..."`. Results come back as global JavaScript
variables or callback functions, asynchronously. Only call schemes when
`isNativeApp()` is true and always keep a web fallback.
Full reference: https://www.webviewgold.com/llms-full.txt
| Feature | Call | Result |
| --- | --- | --- |
| Request push permission | `registerpush://` | native permission prompt |
| Check push permission | `checkNativePushPermissions://` | `nativePushEnabled` (true/false) |
| OneSignal subscription ID | `getonesignalplayerid://` | `onesignalplayerid` |
| Local scheduled notification | `sendlocalpushmsg://push.send?s=SECONDS=msg!MESSAGE&!#TITLE&!#URL` | - |
| Share sheet | `shareapp://message?=TEXT&url=URL` | - |
| Haptics | `lighthaptic://`, `successhaptic://`, `errorhaptic://` | - |
| Biometric check | `bioauth://` | iOS: `onBioAuthSuccess()`, `onBioAuthFailure(code, msg)`, `onBioAuthUnavailable()` |
| QR scanner | `qrcode://` | scanned URL is loaded in the WebView |
| Barcode scanner | `barcodescanner://` | `barcodescanresult` |
| In-app purchase (RevenueCat) | `revenuecat://purchase?external_id=USER_ID&product=PRODUCT_ID` | entitlement in RevenueCat; grant server-side via webhook |
| Restore purchases | `restoreinapppurchases://` | - |
| Manage subscription | `cancelinapppurchase://` | opens the store subscription page |
| App version | `getappversion://` | `versionNumber`, `bundleNumber` |
| Install ID | `get-uuid://` | `uuid` |
| Save image to gallery | `savethisimage://?url=IMAGE_URL` | - |
| Open system app settings (Android) | `settingsapp://` | - |
Injected variables arrive after a short delay: poll with a timeout, never read
them synchronously after the navigation.
## Store rules (every change must keep these true)
- /privacy and /terms are real routes, linked from the footer and from settings.
- Users who can sign up can delete their account in settings (server-side deletion)
and via a public /delete-account page.
- If any third-party login exists, Sign in with Apple is offered as an equal option.
- Digital goods, subscriptions and credits are bought through the bridge
(`revenuecat://purchase...`) when `isNativeApp()`; Stripe stays for browser users.
Never show card forms or external payment links for digital goods in the native app.
Physical goods and services may use Stripe everywhere.
- Layout works from 320px width, tap targets >= 44px, safe-area insets on fixed bars,
inputs with font-size >= 16px.
- Every fetch has loading, empty, error and retry states. No blank screens.
- User-generated or AI-generated content has a report action; users can block others.
- No placeholder copy, no dead links, no mixed content.
## Commands
- Install: `npm install`
- Dev server: `npm run dev`
- Lint and typecheck: `npm run lint && npm run typecheck`
- Tests: `npm test`
Run lint and tests before you finish a task.
## Definition of done for any task
1. Works in a desktop browser and at 320px width.
2. Native-only code is behind `isNativeApp()` with a web fallback.
3. No new store-rule violations (see above).
4. Summarize what changed and what to test on a real device.What each part does
Runtime context
The user agent marker is the key. Set a custom user agent in WebViewGold (useragent_iphone and useragent_ipad in Config.swift, USER_AGENT in Config.java) that contains your marker, and the web app can tell app from browser with one helper.
Bridge table
The exact schemes and the names of the injected variables. This is the part agents hallucinate most. Keep only the rows you use; for everything else, point to llms-full.txt instead of pasting the whole documentation.
Store rules
Written as invariants, not as a to-do list, so they apply to every future task. The payment rule is the expensive one: Apple 3.1.1 rejects digital goods sold outside in-app purchase.
Commands and definition of done
Codex runs commands in its sandbox when you tell it which ones exist. The definition of done makes it report device tests you still have to do yourself.
My iOS WebView is finally approved. Thanks!!
Adopt it in ten minutes
Copy, fill, trim
Replace the placeholders, delete bridge rows you will not use, and adjust the commands to your package manager.
Set the user agent marker in WebViewGold
Config.swift:
useragent_iphoneanduseragent_ipad; Config.java:USER_AGENT. Keep the default user agent string and append your marker (for exampleMYAPPNATIVE/1.0) so websites and OAuth providers still recognize the device.Let Codex create the helper
Use the prompt below. It creates
isNativeApp()and replaces inline user agent checks, so the rest of the file has something to refer to.Commit the file
AGENTS.md is read from the repository, so Codex in the cloud, the CLI and the IDE extension all see the same rules. Nested AGENTS.md files in subfolders add folder-specific instructions.
First prompt after adding the file
Paste into Codex
Read AGENTS.md first. Then: 1) implement isNativeApp() in src/lib/platform.ts based on the user agent marker described there, and replace every inline user agent check in the codebase with it; 2) add a native Share button to the item detail page: inside the native app use the share sheet call from the bridge table in AGENTS.md; in browsers use the Web Share API when available, otherwise copy the link to the clipboard with a short confirmation; 3) trigger success haptics after a successful save, native app only. Keep the existing design. Report what you changed and which rules from AGENTS.md you applied.
What not to put in AGENTS.md
- Secrets or API keys. The file is committed and shown to the model; keep keys in environment variables.
- The entire WebViewGold documentation. Link llms-full.txt and keep the table short; a long file dilutes the rules that matter.
- Store listing copy. Descriptions and keywords belong in the console, not in agent instructions.
- Rules that contradict the code ("we use Tailwind" when you do not). Codex trusts the file and will produce inconsistent code.
- Vague goals ("make it great"). Write invariants it can check, like the store rules section.
Frequently asked questions
Does Codex in the cloud read AGENTS.md too?
Yes. Cloud tasks run against a clone of your repository, so the committed file is picked up like it is in the CLI and the IDE extension.
How do I know Codex is following the file?
Ask it to list the rules it applied at the end of each task (the template asks for this in the definition of done), and read the pull request summary. If a rule is ignored repeatedly, move it higher in the file and make it more concrete.
Should the bridge table list every WebViewGold feature?
No. Keep the rows for features you use or plan to use and link https://www.webviewgold.com/llms-full.txt for the rest. The agent can read the full documentation when a task needs a feature that is not in the table.
Can I use the same file for Lovable or Bolt projects?
Those builders do not read AGENTS.md, but the store rules section works as a prompt: paste it into the builder chat before asking for a change.
Three ways to get your app into the stores
Same result, different amount of work on your side. All three come with the approval guarantee and 24/7 human support.
Do it yourself
$109 per platform, one-time
The WebViewGold license: a finished Xcode or Android Studio project. Paste your URL, set name and icon, switch on features, build and submit. Free updates forever.
See plans on the main pageCloud Builder
$349 per license, one-time add-on
No Mac, no Xcode, no Android Studio: configure in the browser, we build both apps in the cloud and hand them to App Store Connect and the Play Console.
How the Cloud Builder works Try the free demoFull Service
$698 per platform $798
Send us your URL and icon. Our team configures, builds and delivers your app within 72 hours, white-label, with source projects. Both platforms for $1,158.
Full Service details Powered by
Winter Sale prices valid until December 31, 2026.