Newly

Newly Documentation Audit

One-line summary: Genuinely useful no-code-to-native-app docs undermined by a cluster of page-to-page contradictions in the highest-stakes area — subscriptions and in-app-purchase testing — plus a confirmed dead-link cluster on the most compliance-sensitive page and an index (llms.txt) that silently omits a major feature and several real guides.

1. The subscription entitlement is documented two ways — "pro" in reference, "premium" in the tutorials (critical)

Location: /subscriptions/overview, /subscriptions/technical-details vs /integrations/revenuecat, /guides/adding-payments

Problem: The reference pages are emphatic that the entitlement name is fixed: overview says "Newly uses a single entitlement called 'pro'… Custom entitlement names are not supported. If a different name is accidentally set, the system auto-corrects it to 'pro'," and technical-details lists revenueCatEntitlementId as pro ("always 'pro'"). But the RevenueCat integration page instructs users to create and check a premium entitlement (entitlements.active['premium']), and the Adding Payments tutorial checks the same ['premium'].

Consequence: A developer who follows the payments tutorial wires their paywall to ['premium'], while the platform forces the actual entitlement to pro. The check never matches, so subscriptions silently never unlock. This is not hypothetical: the docs' own /subscriptions/troubleshooting lists this exact failure as the #1 cause of "No subscription plans available" — "Entitlement mismatch — your app expects an entitlement that doesn't match what's in RevenueCat. Newly uses 'pro' as the entitlement name." The docs are simultaneously the cause and the cure.

The fix: Pick one entitlement name and use it everywhere. Since the platform hardcodes pro, rewrite the RevenueCat integration page and the Adding Payments guide to create and check pro, and remove every ['premium'] example.

2. Monthly-only billing (reference) vs yearly subscriptions (tutorials) (critical)

Location: /subscriptions/pricing-and-products vs /integrations/revenuecat, /guides/adding-payments

Problem: pricing-and-products states flatly: "Newly currently supports monthly subscriptions only — annual and other billing periods are not yet available. Each product supports a single price." Yet the RevenueCat integration page promotes monthly ($9.99) and yearly ($79.99) options with a best practice to offer both, and the Adding Payments tutorial builds a yearly subscription ($79.99/year) end to end.

Consequence: A developer follows the tutorial to build an annual plan, then discovers the platform can't ship one. Time is spent designing a paywall and pricing strategy around a tier that doesn't exist, and the contradiction erodes trust in every other claim in the subscriptions section.

The fix: If annual billing genuinely isn't supported, strip the yearly examples from the integration and tutorial pages (or mark them clearly as "not yet available"). If it is supported, correct the pricing-and-products limitation statement.

3. Supabase is "paused" on one page and "connect it today" on another (critical)

Location: /integrations/supabase vs /features/backend

Problem: The Supabase Integration page leads with a banner: "New Supabase connections are temporarily paused. As of April 2026, you can't connect a new Supabase project to Newly while we rework the integration." But /features/backend presents Supabase as a fully selectable backend with live OAuth steps ("Connecting Supabase / Newly uses OAuth to securely connect to your Supabase project: Click More → Supabase in the project menu… Click 'Connect Supabase'…") and a backend-comparison table — with no pause notice anywhere on the page.

Consequence: A new user reading the Backend Systems page believes they can connect Supabase right now, walks through the OAuth steps, and hits a disabled flow with no explanation — because the page that explains the pause is one they never had a reason to open.

The fix: Surface the April-2026 pause banner on every page that presents Supabase connection as an option (starting with /features/backend), or gate those flows behind the same notice until the integration is re-enabled.

4. Dead-link cluster: the Permissions guide links seven /articles/* pages that don't exist (critical)

Location: /guides/permissions-and-entitlements

Problem: The Apple and Android entitlement tables link out to deeper guides at /articles/family-controls-entitlement, /articles/critical-alerts-entitlement, /articles/carplay-entitlement, /articles/network-extension-entitlement, /articles/health-records-entitlement, /articles/ios-default-app-entitlement, and /articles/android-restricted-permissions. Five were directly probed and returned HTTP 404 (family-controls, critical-alerts, carplay, health-records, android-restricted-permissions); the remaining two (network-extension, ios-default-app) are almost certainly dead as well — there is no /articles/ section anywhere in the docs index (llms.txt).

Consequence: Every "deeper guide" link in the platform's most compliance-sensitive page (managed Apple entitlements, App Review gating, Google Play restricted permissions) is a dead end. A developer trying to ship an app that needs Family Controls or Critical Alerts gets a table that promises detail and delivers a 404.

The fix: Either publish the /articles/* pages or replace the links with the relevant Apple/Google documentation URLs. At minimum, de-link the table cells so they don't advertise content that doesn't exist.

5. In-app-purchase and auth flows can't be tested in Expo Go — and the docs say so only after you've already hit it (significant)

Location: /subscriptions/testing, /subscriptions/troubleshooting

Problem: The testing page states the constraint plainly: "Purchases do not work in standard Expo Go. The RevenueCat SDK and SecureStore (used for credential storage) are not available in Expo Go," and instructs users to make a custom dev build (npx expo prebuild) or a production build. The troubleshooting page reinforces that this is a common failure, listing "'Invalid API key' error in Expo Go" as a recurring issue — "RevenueCat purchases do not work in standard Expo Go. You need a custom dev build."

Consequence: Because SecureStore is also unavailable in Expo Go, both subscription and credential/auth flows silently fail in the standard quick-run client — and the docs' own troubleshooting confirms developers routinely hit this. A developer iterating in Expo Go can never verify their paywall or sign-in works, and the blocking requirement (a custom native dev build) is only documented on two deep subscriptions pages, not at the point where testing first comes up.

The fix: Surface the Expo Go limitation prominently at the top of any testing or getting-started flow that touches purchases or auth: state up front that purchase and credential testing require a custom dev build, with the npx expo prebuild step inline.

6. A major feature (Marketing Studio) and several real guides are absent from the docs index (significant)

Location: /features/marketing-studio, /llms.txt

Problem: /features/marketing-studio is a substantial page (video generation via Seedance, image generation via Nano Banana, an Instagram outreach agent with Apify/Resend provider config) and is cross-linked from changelog entries via "Learn more." Yet it is entirely absent from llms.txt. It is not alone: /advanced/exporting-code, /guides/cancel-subscription, /guides/save-prompts, /guides/first-app, and /guides/using-logs-to-debug all exist (each has live content) but none of them appear in llms.txt either.

Consequence: The published index — the thing both humans and AI agents use to discover what exists — has no path to a whole feature surface plus key billing and debugging guides. Anyone who didn't happen to read the right changelog entry never finds Marketing Studio, and an agent indexing llms.txt cannot surface any of these pages at all.

The fix: Add /features/marketing-studio and the missing guide pages to llms.txt. Then audit the index against the actual page set on every release so feature and guide pages can't drift out of it again.

7. Two different AI-chat pages on two different path conventions (significant)

Location: /features/ai-chat ("Prompting") and /documentation/features/ai-chat ("AI Chatbot")

Problem: llms.txt lists two AI-chat pages: "Prompting" at /features/ai-chat and "AI Chatbot" at /documentation/features/ai-chat. Every other feature page lives under /features/; this is the only one duplicated under a /documentation/features/ prefix. The two overlap confusingly in subject (building AI features / the conversational interface).

Consequence: Readers and agents can't tell which page is canonical, search surfaces both, and the orphan /documentation/features/ prefix suggests a second, parallel doc tree that nothing else uses.

The fix: Consolidate to a single AI-chat page under the standard /features/ path, and redirect or delete the duplicate. If both are intentional (prompting vs chatbot-building), retitle them so the distinction is obvious and put both under /features/.

8. The deploy flow is named different ways across pages (significant)

Location: /features/deployment, /subscriptions/app-store-connect-setup

Problem: The single most important action — deploying — has inconsistent entry-point descriptions. deployment says "Choose 'Build for iOS' in the Deploy modal" and, for backend, "Click More → Deploy App." app-store-connect-setup says "Open the Deploy modal in the Newly dashboard (click 'Deploy' on your project)" then "Click Build & Deploy and select iOS." So the same flow is labeled "Deploy App," "Deploy," and "Build & Deploy" across two pages.

Consequence: A user hunting for "Deploy App" under a More menu, per one page, won't find the "Deploy" button or "Build & Deploy" action described by another. Inconsistent UI labels for the same flow make the docs hard to follow against the actual product.

The fix: Pin down the real UI label and menu path, then use that exact wording on every page that opens the deploy flow.

9. The iOS build instructions are garbled and reference an undefined "Expo Launch" (significant)

Location: /features/deployment

Problem: Under "Building for iOS," a GitHub flow is interleaved into the Apple-credentials steps with no transition: "Choose 'Build for iOS' in the Deploy modal" is followed by a bare bullet list — "Migrate to Github / Make the Repo public / Copy the Repo link / Open Expo Launch and paste the Repo link" — and then jumps to "Provide your Apple Developer credentials." "Expo Launch" is never defined anywhere in the docs, and making the repo public is stated with no rationale or warning.

Consequence: A developer following the iOS build can't tell whether the GitHub steps are required, optional, or a copy-paste error, doesn't know what "Expo Launch" is, and may make a private repo public without understanding why. The core ship-to-App-Store path is the worst place for ambiguity.

The fix: Rewrite the section as a single ordered sequence, define "Expo Launch" (or remove it), explain why/whether the repo must be public, and separate the GitHub steps from the Apple-credentials steps.

10. Refund/cancellation page still speaks in "prompts" after the May-2026 rename to "credits" (significant)

Location: /guides/cancel-subscription vs /faq, /changelog/2026-05-18

Problem: The FAQ states the term changed: "We switched the term from prompts to credits in May 2026," and the 2026-05-18 changelog confirms "'Credits' replaces 'prompts.'" But the cancel-subscription refund policy is still written entirely in the old vocabulary: "we process refunds only if you have used less than 5% of your monthly AI prompts… on the standard plan (50 prompts per month), you are not eligible for a refund if you have used more than 2 prompts." The save-prompts page compounds the drift: its URL slug is save-prompts while the title is "How to save credits."

Consequence: Billing and refund eligibility is exactly where stale terminology causes real confusion — a user reading "prompts" can't map it to the "credits" balance they actually see in the Usage tab. There's also a math ambiguity: "less than 5%" of 50 is 2.5, but the worked example draws the line at "more than 2," leaving the eligibility threshold genuinely unclear.

The fix: Replace "prompts" with "credits" across cancel-subscription, restate the refund threshold unambiguously (a clear credit count rather than a percentage that rounds awkwardly), and align the save-prompts slug with its "credits" title via a redirect.

11. "Run it locally" instructions disagree on the package manager (minor)

Location: /features/code-editor, /advanced/exporting-code, /integrations/github

Problem: The exported-project run instructions aren't consistent. Code Editor documents npm in both export paths (GitHub clone and Download ZIP): "Install: npm install / Run: npx expo start." The Exporting Code page's "Running Locally" section, by contrast, specifies only "Ensure you have Node.js 18+ installed" and names no package manager or run command, while the GitHub Integration page's "Working Locally" steps are pnpm-based rather than npm.

Consequence: A developer copy-pasting local setup gets different commands depending on which page they landed on, and a user who installs with one manager and runs lockfile-generating commands from another can produce conflicting lockfiles. The only fully spelled-out, verified path is Code Editor's npm steps; the others are either incomplete or use a different tool.

The fix: Standardize on one package manager across code-editor, exporting-code, and github, and give each "run locally" section the same complete install + start commands.

12. The same AI-chat page says "No API keys required" while also telling you to add API keys (minor)

Location: /documentation/features/ai-chat

Problem: The page opens with "No manual API setup. No configuration headaches. No API keys required by default," then a few lines later says: "If you want to integrate a specific AI provider or model, simply add its API key in the Database → Secrets section."

Consequence: The two statements are technically reconciled by "by default," but that qualifier sits in a list of three emphatic "No …" claims and is easy to miss. A developer who needs a specific model (the common case for anything beyond the default) reads the headline as a blanket promise and is mildly surprised to find keys are required after all. This is a wording-clarity issue, not a functional contradiction.

The fix: Reframe the headline to "No keys required to start; add your own provider key when you want a specific model," so the default-vs-custom distinction is stated up front rather than walked back.

13. "Clerk" is named as an auth provider but documented nowhere (minor)

Location: /subscriptions/authentication

Problem: The page says purchases sync "When your app has authentication (e.g. via Clerk or Supabase)." Clerk appears nowhere else in the docs — no integration page, no setup guide, no index entry. Everywhere else, auth is Liquid Backend's built-in Email/Google/Apple or Supabase Auth.

Consequence: A developer reads "via Clerk," assumes Clerk is a supported integration, and goes looking for a setup guide that doesn't exist. The orphan reference implies a capability the docs never back up.

The fix: Either add a Clerk integration page or replace the example with a provider Newly actually documents (Liquid Backend auth or Supabase Auth).

14. The backend has a second name, "Specular," that's never defined (minor)

Location: /guides/using-logs-to-debug vs /concepts, /features/backend

Problem: The debugging guide labels backend logs "Backend logs (Specular - Liquid Backend)" and says "Newly pulls these from Specular." "Specular" is introduced here with no definition; Core Concepts and Backend Systems only ever call the backend "Liquid Backend."

Consequence: A user reading their logs sees "Specular," a term defined nowhere in the conceptual docs, and can't tell whether it's the backend, a separate service, or a typo. Undefined internal names in logs increase support load.

The fix: Define "Specular" once where the backend is introduced (Core Concepts / Backend Systems), or drop it and call the backend "Liquid Backend" consistently in the logs guide.

What they do well

• The subscriptions section has a real troubleshooting page that names concrete failure modes ("No subscription plans available," "Invalid API key in Expo Go") with specific fixes — rare and genuinely useful, even though it inadvertently documents the platform's own pro/premium contradiction.
• Honest about limitations where it counts: pricing-and-products clearly states monthly-only and single-tier constraints, and the Supabase page is upfront that migration back from Liquid Backend isn't possible.
• An llms.txt index exists at all, giving agents a machine-readable starting point — the gap is keeping it in sync, not its absence.

Top 3 recommendations

1. Fix the subscriptions contradictions first — unify the entitlement name on pro everywhere and remove ['premium'] from every tutorial, then reconcile monthly-vs-yearly. This is the area where wrong docs produce silently broken payments.
2. Make the test loop honest — put the Supabase April-2026 pause banner on /features/backend, and surface the Expo Go "no purchases/no auth, use a dev build" constraint at the start of testing guidance so no one starts a disabled or untestable flow.
3. Make the index authoritative — add Marketing Studio and the missing guide pages to llms.txt, and fix or de-link the seven dead /articles/* links so humans and agents can trust what the index says exists.