Improve documentation SEO and agent retrieval

.github/workflows/build-errors-check.yml

@@ -15,12 +15,16 @@ jobs:
           fetch-depth: 0
 
       - name: Install Dependencies
-        run: npm install
+        run: npm ci
+
+      - name: Typecheck
+        run: npm run typecheck
 
       - name: Build
         run: npm run build
 
+      - name: Audit SEO and agent artifacts
+        run: npm run audit:seo-agent:built
 
-
-
-
+      - name: Evaluate agent retrieval
+        run: npm run eval:agent-retrieval

.github/workflows/content-freshness.yml

@@ -0,0 +1,37 @@
+name: Documentation Freshness SLA
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: '17 8 * * 1'
+
+jobs:
+  freshness-audit:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout full history
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build canonical artifacts
+        run: npm run build
+
+      - name: Enforce freshness SLA
+        id: freshness
+        continue-on-error: true
+        run: npm run audit:seo-agent:strict
+
+      - name: Upload freshness report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: documentation-freshness-report
+          path: reports/seo-agent-audit.*
+
+      - name: Fail when pages exceed SLA
+        if: steps.freshness.outcome == 'failure'
+        run: exit 1

.gitignore

@@ -3,6 +3,7 @@
 
 # Production
 /build
+/reports
 
 # Generated files
 .docusaurus

CONTENT_QUALITY.md

@@ -0,0 +1,99 @@
+# Documentation search and agent quality standard
+
+This repository treats human search, web search, and AI-agent retrieval as one publishing system. A page is not complete merely because it renders: it must be discoverable, uniquely identifiable, current, accessible, and safe to use as cited answer context.
+
+## A+ release gates
+
+An A+ metric is at least 98%. The production build and `npm run audit:seo-agent:built` measure the following gates:
+
+| Metric | A+ requirement |
+| --- | --- |
+| Crawl and indexation | Every canonical page is allowed by `robots.txt`, appears once in the sitemap, has an evidence-based `lastmod`, and no generated search, tag, or archive route appears in the sitemap. |
+| Metadata | Every page has a unique title and description, 2–3 controlled tags, and at least three query-oriented keywords. Titles are at most 65 characters and descriptions are 50–180 characters. |
+| Content structure | The built page has exactly one H1, at least 50 visible words, and at least one contextual internal link unless it is the site root. Broken links and anchors fail the Docusaurus build. |
+| Accessibility | Every image has useful alt text and every embedded tutorial has a non-empty title. |
+| Performance | No JavaScript chunk exceeds 250 KB gzip, no canonical HTML file exceeds 250 KB, referenced instructional media stays below 2 MB, and third-party chat loads only after interaction. |
+| Freshness | At least 98% of pages are within their review SLA: 180 days for volatile material and 365 days for standard material. |
+| Agent discovery | Every canonical page has page-level Markdown, appears in `llms.txt`, belongs to at least one bounded topic pack, and is present in the agent manifest. No topic pack exceeds 500,000 characters. |
+| Structured data | Every built documentation page includes valid `TechArticle` JSON-LD with a canonical URL and publisher. |
+| Retrieval quality | On the fixed intent set: recall@5 ≥98%, top-1 accuracy ≥90%, and canonical evidence coverage ≥98%. |
+| Live answer quality | On a separately approved and recorded model run: answer correctness ≥95%, citation support ≥98%, and unsupported-claim rate <1%. This is not inferred from the static retrieval score. |
+
+## Required front matter
+
+Every page must include:
+
+```yaml
+---
+slug: /canonical-route
+title: Task-specific title
+description: A unique 50–180 character summary that says what the reader can accomplish.
+tags: [FlutterFlow, Controlled Product Area]
+keywords: [FlutterFlow, user query phrase, feature name]
+last_verified: 2026-09-01
+---
+```
+
+Only add `last_verified` after checking the instructions against the current product. Metadata cleanup, link checking, or a successful build alone does not count as product verification.
+
+## Page design for answer engines
+
+A task guide should state the outcome in its opening paragraph and use this order when relevant:
+
+1. What the feature does and when to use it.
+2. Availability, plan, platform, and prerequisite constraints.
+3. Numbered steps using current UI labels and navigation paths.
+4. A verifiable expected result.
+5. Common failure modes and safe recovery steps.
+6. Related canonical guides.
+
+Put critical facts in text. Images and videos supplement the procedure; they do not replace it. Use exact FlutterFlow UI labels in bold. Prefer one canonical page per intent and link aliases or broader overviews to it.
+
+## Terminology that agents must distinguish
+
+- **AI Agent** is the FlutterFlow desktop feature for using external coding agents to edit a FlutterFlow project.
+- **AI Agents** is the runtime integration for adding AI-powered experiences to an app.
+- **Codex CLI** is the terminal interface. **Codex in the ChatGPT desktop app** is the desktop surface. State which surface a procedure applies to.
+- **Test Mode**, **Run Mode**, **Local Run**, and deployed builds are distinct environments. Do not use the names interchangeably.
+- **Generated code** describes exported Flutter code. It is not the same as project configuration edited through the FlutterFlow CLI or MCP tools.
+
+## Freshness workflow
+
+Volatile sections include integrations, deployment, testing, CLI/agent tooling, accounts and billing, and troubleshooting. They must be verified every 180 days. Other pages must be verified every 365 days.
+
+For each review:
+
+1. Reproduce the task in the current product or obtain confirmation from the owning product team.
+2. Verify plan, platform, region, and role prerequisites.
+3. Confirm every UI label, navigation path, code sample, external link, and expected result.
+4. Remove obsolete alternatives and redirect duplicate pages to the canonical guide.
+5. Update `last_verified` to the review date and include public evidence in the pull request when appropriate. Keep private source revisions, implementation paths, excerpts, and review notes in an approved private system; never add them to this public repository or its Git history.
+6. Run `npm run build` and `npm run audit:seo-agent:built`.
+
+The audit uses `last_verified` when present. For pages included in the repository-wide SEO migration, it otherwise uses `freshness-baseline.json`, which preserves the last pre-migration content evidence date. New pages fall back to their most recent Git commit. This prevents a metadata-only migration from making old product instructions look newly verified. Stale pages remain visible as warnings until a real product review occurs.
+
+## Agent artifacts
+
+The build publishes:
+
+- `/llms.txt`: canonical page inventory and bounded topic-pack index.
+- `/llms-full.txt`: complete canonical corpus for consumers that explicitly want it.
+- `/llms/<topic>.txt`: focused context packs kept below the configured context budget.
+- `/<canonical-route>.md`: page-level Markdown with canonical URL, source file, and last-updated metadata.
+- `/agent-content-manifest.json`: machine-readable inventory for validation and downstream ingestion.
+
+Search, tag, blog, and other navigation-only routes are excluded. The postbuild generator reads Docusaurus's resolved metadata, so relative slugs and generated category indexes use the same canonical routes as the rendered site.
+
+## Commands
+
+```bash
+npm run remediate:docs       # Reapply deterministic metadata/accessibility normalization from HEAD
+npm run typecheck            # Validate theme and component TypeScript
+npm run build                # Build and generate sitemap/agent artifacts
+npm run audit:seo-agent      # Source-only scorecard
+npm run audit:seo-agent:built
+npm run audit:external-links # Network check; review timeouts manually
+npm run eval:agent-retrieval
+```
+
+Do not run the remediation command after making uncommitted manual documentation edits: it intentionally rebuilds documentation files from `HEAD` so the large migration is reproducible.

README.md

@@ -12,6 +12,8 @@ Either way, you'll need to open up a pull request and get approval from at least
 ## Contribution Guidelines
 Before you start contributing, please take a moment to review our [Contribution Guidelines](https://flutterflow.notion.site/Docs-Contribution-Guidelines-42829c305df441f6b061b4095abac8a8). This document outlines the process and expectations for contributions to ensure a smooth collaboration.
 
+All changes must also follow the repository's [documentation search and agent quality standard](CONTENT_QUALITY.md). New task pages should start from [the task-guide template](templates/task-guide.md). Include public evidence in the pull request when appropriate, and keep any private implementation evidence in an approved private system rather than this public repository.
+
 ## How to Contribute
 1. **Editing Existing Pages**:
    To make edits to an existing page in [docs.flutterflow.io](https://docs.flutterflow.io), you can use the "Edit this page" button that appears at the bottom of each page. This button will bring you straight to the source of the page in GitHub.
@@ -27,6 +29,7 @@ You may want to run the docs site locally to test and visualize changes you are
 
 1. **Install Dependencies:** Run **`npm install`** in your terminal to install the necessary dependencies.
 2. **Preview Changes:** To see your changes in real-time as you edit the files, you can run a local development server. This server will host your website and reflect the latest changes. Use the command **`npm run start`**.
+3. **Validate Search and Agent Quality:** Run **`npm run typecheck`**, **`npm run build`**, and **`npm run audit:seo-agent:built`** before opening a pull request.
 
 ## Deploying a Staging Preview
 To share your branch with reviewers before merging, deploy it to a Firebase Hosting preview channel. This builds the site and publishes it to a temporary URL (defaults to a 7-day expiry).

docs/accounts-billing/account-management.md

@@ -1,11 +1,19 @@
 ---
 slug: account-management
 title: Account Management
-tags: []
+tags:
+  - FlutterFlow
+  - Accounts & Billing
 toc_max_heading_level: 5
 sidebar_position: 1
+description: >-
+  This section contains information on changing your password, verifying your
+  email, and deleting your account.
+keywords:
+  - Account Management
+  - Accounts Billing
+  - FlutterFlow
 ---
-
 # Account Management
 This section contains information on changing your password, verifying your email, and deleting your account.
 
@@ -41,7 +49,7 @@ To check if you have verified your account:
 If you did not receive a verification email, please follow these steps:
 
 1. Navigate to your [account page in FlutterFlow](https://app.flutterflow.io/account).
-2. Check that your email address is correct. If your email is incorrect, please reach out to `support@flutterflow.io` to correct this. 
+2. Check that your email address is correct. If your email is incorrect, please reach out to `support@flutterflow.io` to correct this.
 3. From the **Profile Information** section, select **Verify Email**.
 
 You should receive a new confirmation email. If you do not receive the verification email, please contact us at support@flutterflow.io.
@@ -62,13 +70,13 @@ This step can not be undone. We will not be able to recover your projects.
 ### How do I change or update my email address?
 To change your login email in FlutterFlow:
 
-1. Log into your FlutterFlow account. 
-2. Go to the dashboard and select your account tile (showing your name and email). 
-3. Click on **Update Email**. 
-4. Enter your current email and password. 
-5. Input your new email and click **Confirm & Log Out**. 
-6. Verify the new email via the link sent to it. 
-7. Now, you need to create a new password for your new email address. To do so, click on the **Forgot Password** on the login page and enter your new email address. 
+1. Log into your FlutterFlow account.
+2. Go to the dashboard and select your account tile (showing your name and email).
+3. Click on **Update Email**.
+4. Enter your current email and password.
+5. Input your new email and click **Confirm & Log Out**.
+6. Verify the new email via the link sent to it.
+7. Now, you need to create a new password for your new email address. To do so, click on the **Forgot Password** on the login page and enter your new email address.
 8. You'll receive the password reset link at your new email address. Click the link and reset the password.
 
 Now, you are ready to log in with your new email address and password.

docs/accounts-billing/manage-custom-domains.md

@@ -1,30 +1,48 @@
-
-
+---
+title: Manage Custom Domains
+description: >-
+  All paid plans include one free custom domain, with the option to purchase
+  more if needed.
+tags:
+  - FlutterFlow
+  - Accounts & Billing
+keywords:
+  - Manage Custom Domains
+  - Accounts Billing
+  - FlutterFlow
+last_verified: 2026-09-02
+---
 # Manage Custom Domains
 
-All paid plans include one free custom domain, with the option to purchase more if needed.
+Paid plans include one custom-domain connection. Additional connections may be purchased; check the current [plan comparison](./new-pricing-comparison.md) and the billing screen for availability and regional pricing. You must obtain the domain itself from a domain registrar.
 
-### How do I purchase additional custom domains?
+### Purchase domain connections
 
-To purchase domains, paid users can go to their [**account**](https://app.flutterflow.io/account) page, find the **Custom Domains** section, and click the **Add Domains** button.
+For a personal plan, go to your [**Account**](https://app.flutterflow.io/account), find **Custom Domains**, and select **Add Domains**.
 
 ![add-domain](imgs/add-domain.avif)
 
 
-The **Team** owner can purchase domains from the **My Team** page. Under the **Custom Domains** section, click **Add Domains** to add one for the team.
+For a team plan, a team owner can open **My Team**, find **Custom Domains**, and select **Add Domains**.
 
 ![add-domain-team](imgs/add-domain-team.avif)
 
 :::note
-Note that purchasing a domain is not possible during the trial period. If you're interested in obtaining a domain, please reach out to our support team for further assistance.
+Additional domain connections cannot be purchased during a trial. Contact FlutterFlow support if the billing screen does not offer the connection your plan requires.
 :::
 
 
 ### How do I remove custom domains?
 
-To remove the custom domain, paid users can go to their [**account**](https://app.flutterflow.io/account) page, find the **Custom Domains** section, and click **Remove Domains** to remove the existing custom domain.
+For a personal plan, open your [**Account**](https://app.flutterflow.io/account), find **Custom Domains**, and select **Remove Domains**.
+
 
+A team owner can remove a team's domain connection from **My Team > Custom Domains > Remove Domains**.
 
-The **Team** owner can remove domain from the **My Team** page. In the **Custom Domains** section, click **Remove Domains**.
+Removing the FlutterFlow connection does not cancel registration of the domain with your registrar. Confirm which deployed project uses the domain before removing it.
 
 ![remove-domain-team](imgs/remove-domain-team.avif)
+
+## Related documentation
+
+See [Account Management](/accounts-billing/account-management) for a related FlutterFlow workflow.

docs/accounts-billing/new-pricing-comparison.md

@@ -1,11 +1,17 @@
 ---
 slug: plan-comparison
-title: "Plan Comparison"
-description: "Compare FlutterFlow plans and features to find the right plan for your needs"
+title: Plan Comparison
+description: Compare FlutterFlow plans and features to find the right plan for your needs
 hide_table_of_contents: true
 sidebar_position: 3
+tags:
+  - FlutterFlow
+  - Accounts & Billing
+keywords:
+  - Plan Comparison
+  - Accounts Billing
+  - FlutterFlow
 ---
-
 <Head>
   <link rel="stylesheet" href="/css/table_style.css" />
 </Head>
@@ -15,14 +21,14 @@ import {useState, useEffect} from 'react';
 export const PricingToggles = () => {
   const [currency, setCurrency] = useState('USD');
   const [billingPeriod, setBillingPeriod] = useState('monthly');
-  
+
   // Update sticky header when pricing changes
   useEffect(() => {
     // Trigger sticky header recreation when pricing data changes
     const event = new CustomEvent('pricingChanged');
     window.dispatchEvent(event);
   }, [currency, billingPeriod]);
-  
+
   const pricingData = {
     USD: {
       monthly: {
@@ -32,10 +38,10 @@ export const PricingToggles = () => {
         business: '1st seat: $150, \n Seats 2-5: $85 each*',
         enterprise: 'Custom'
       },
-      annual: { 
+      annual: {
         free: 0,
         individual: 351, // $360/year = $30/month effective
-        growth: '1st seat: $720, \n 2nd seat: $495', 
+        growth: '1st seat: $720, \n 2nd seat: $495',
         business: '1st seat: $1,350, \n Seats 2-5: $765*', // $4752/year = $396/month effective
         enterprise: 'Custom'
       }
@@ -771,3 +777,7 @@ Includes all Business features, plus the ability to add up to 7 additional seats
 
 ### Localized Pricing
 INR pricing reflects localized rates adjusted for local purchasing power, providing the same features and plan structures as USD pricing. All plans include the same comprehensive feature set regardless of currency.
+
+## Related documentation
+
+See [Account Management](/accounts-billing/account-management) for a related FlutterFlow workflow.