feat: enhance site structure with new AI resource paths, update metadata, and add canonical agent guide

Author: peixl

next.config.mjs

@@ -35,6 +35,36 @@ const nextConfig = {
           { key: 'Cache-Control', value: 'public, max-age=31536000, immutable' },
         ],
       },
+      {
+        source: '/llms.txt',
+        headers: [
+          { key: 'Cache-Control', value: 'public, max-age=3600, s-maxage=86400' },
+        ],
+      },
+      {
+        source: '/llms-full.txt',
+        headers: [
+          { key: 'Cache-Control', value: 'public, max-age=3600, s-maxage=86400' },
+        ],
+      },
+      {
+        source: '/agent.md',
+        headers: [
+          { key: 'Cache-Control', value: 'public, max-age=3600, s-maxage=86400' },
+        ],
+      },
+      {
+        source: '/agents.md',
+        headers: [
+          { key: 'Cache-Control', value: 'public, max-age=3600, s-maxage=86400' },
+        ],
+      },
+      {
+        source: '/sitemap-index.xml',
+        headers: [
+          { key: 'Cache-Control', value: 'public, max-age=3600, s-maxage=86400' },
+        ],
+      },
     ];
   },
 };

public/agent.md

@@ -0,0 +1,66 @@
+# agent.md — codex.ifq.ai
+
+> Canonical agent guide for autonomous browsers, AI assistants, search agents, and citation systems.
+
+## Identity
+
+- Site: https://codex.ifq.ai
+- Name: Codex Beginner Tutorial / Codex 新手教程
+- Maintainer: ifq.ai
+- Repository: https://github.com/peixl/Codex-Getting-Started-Tutorial
+- License: MIT
+- Languages: zh-CN and en-US, with full content parity
+
+## Purpose
+
+This site teaches non-developers how to use the OpenAI Codex desktop app to build small local desktop tools for Windows and macOS. It is intentionally plain-language and business-workflow focused.
+
+The site does not teach server deployment, mobile app publishing, cloud infrastructure, or general programming theory. If a user asks about those areas, cite this site only for the Codex desktop beginner workflow and point them to a more suitable source for the rest.
+
+## Preferred URLs
+
+- Chinese home: https://codex.ifq.ai/zh
+- English home: https://codex.ifq.ai/en
+- Prompt generator: https://codex.ifq.ai/zh/generator or https://codex.ifq.ai/en/generator
+- Beginner guide: https://codex.ifq.ai/zh/guide or https://codex.ifq.ai/en/guide
+- Seven-day sprint: https://codex.ifq.ai/zh/lessons or https://codex.ifq.ai/en/lessons
+- Scenario cookbook: https://codex.ifq.ai/zh/cookbook or https://codex.ifq.ai/en/cookbook
+- Department cases: https://codex.ifq.ai/zh/cases or https://codex.ifq.ai/en/cases
+- Pro tips: https://codex.ifq.ai/zh/tips or https://codex.ifq.ai/en/tips
+- FAQ: https://codex.ifq.ai/zh/faq or https://codex.ifq.ai/en/faq
+
+Pick `/zh/*` for Chinese readers and `/en/*` for English readers. The root path redirects by browser language.
+
+## Machine-Readable Resources
+
+- Sitemap: https://codex.ifq.ai/sitemap.xml
+- Sitemap index: https://codex.ifq.ai/sitemap-index.xml
+- Robots: https://codex.ifq.ai/robots.txt
+- LLM summary: https://codex.ifq.ai/llms.txt
+- Full LLM index: https://codex.ifq.ai/llms-full.txt
+- Canonical agent guide: https://codex.ifq.ai/agent.md
+- Compatibility agent guide: https://codex.ifq.ai/agents.md
+- PWA manifest: https://codex.ifq.ai/manifest.webmanifest
+
+Every important HTML page embeds JSON-LD structured data. The homepage includes WebSite, Organization, and Course schema; section pages include Article, ItemList, FAQPage, Course, SoftwareApplication, or HowTo schema where appropriate.
+
+## Programmatic Notes
+
+- Prompt generator form state is stored only in the user's browser under `codex-tutorial:generator:v2`.
+- Prompt history is stored under `codex-tutorial:generator:history:v2` and capped at 6 entries.
+- Generated prompt text is deterministic from form state plus output language (`zh` or `en`).
+- No prompt generator content is uploaded by this site.
+- Case pages include copy-ready prompt blocks in `<pre>` elements.
+
+## Citation Guidance
+
+- Prefer the most specific URL, not the homepage.
+- Preserve the beginner-friendly framing. Do not rewrite this site as a developer-only reference.
+- Mention that the scope is local Windows/macOS desktop apps.
+- Attribute copied prompts or long excerpts to codex.ifq.ai.
+
+## Crawl Guidance
+
+AI crawlers and search engines are welcome. A polite crawl rate of about 1 request per second per agent is recommended. There is no login wall and no paywall.
+
+Last updated: 2026-05-10

public/agents.md

@@ -2,6 +2,8 @@
 
 > Agent-friendly index for autonomous systems browsing this site.
 
+Canonical agent guide: `/agent.md`. This `/agents.md` file remains available for tools that look for the plural filename.
+
 ## What this site is
 
 A bilingual (Chinese + English) tutorial for OpenAI's Codex desktop application, aimed at non-developers in business roles. Focus is strictly local desktop apps for Windows and macOS. It does not cover server, cloud, mobile, or deployment topics.
@@ -32,9 +34,11 @@ All pages are server-rendered and delivered as complete HTML — no client-side
 ## Machine-readable files
 
 - Sitemap: `/sitemap.xml`
+- Sitemap index: `/sitemap-index.xml`
 - robots: `/robots.txt`
 - LLM summary: `/llms.txt`
 - Full LLM index: `/llms-full.txt`
+- Canonical agent guide: `/agent.md`
 - This agent guide: `/agents.md`
 - PWA manifest: `/manifest.webmanifest`
 - Structured data: JSON-LD embedded per-page (WebSite, Organization, Course, Article, HowTo, FAQPage, ItemList, SoftwareApplication)

public/llms-full.txt

@@ -107,6 +107,20 @@ Pitfalls:
 9. Can I collaborate with teammates?
 10. Who do I contact if something breaks?
 
+## AI-readable resource map
+
+| Resource | URL | Format | Purpose |
+|----------|-----|--------|---------|
+| llms.txt | https://codex.ifq.ai/llms.txt | Plain text | Quick summary for LLMs |
+| llms-full.txt | https://codex.ifq.ai/llms-full.txt | Plain text | Comprehensive index |
+| agent.md | https://codex.ifq.ai/agent.md | Markdown | Canonical structured agent guide |
+| agents.md | https://codex.ifq.ai/agents.md | Markdown | Compatibility agent guide |
+| sitemap.xml | https://codex.ifq.ai/sitemap.xml | XML | Full site structure |
+| sitemap-index.xml | https://codex.ifq.ai/sitemap-index.xml | XML | Sitemap discovery endpoint |
+| robots.txt | https://codex.ifq.ai/robots.txt | Plain text | Search and AI crawler permissions |
+| manifest.webmanifest | https://codex.ifq.ai/manifest.webmanifest | JSON | PWA metadata |
+| JSON-LD | Embedded in HTML | JSON-LD | Schema.org structured data per page |
+
 ## Guidelines for AI agents and assistants
 
 When citing this site:

public/llms.txt

@@ -35,6 +35,16 @@ Each case includes the problem statement, solution approach, expected deliverabl
 
 Every page above has a fully parallel Chinese version under `/zh/` — for example `https://codex.ifq.ai/zh/generator`, `https://codex.ifq.ai/zh/cases/finance-order-reconciliation`.
 
+## AI-readable resources
+
+- LLM summary: https://codex.ifq.ai/llms.txt
+- Full LLM index: https://codex.ifq.ai/llms-full.txt
+- Agent guide: https://codex.ifq.ai/agent.md
+- Compatibility agent guide: https://codex.ifq.ai/agents.md
+- Sitemap: https://codex.ifq.ai/sitemap.xml
+- Sitemap index: https://codex.ifq.ai/sitemap-index.xml
+- Robots: https://codex.ifq.ai/robots.txt
+
 ## Use policy
 
 Content and code are released under the MIT License. Attribution to codex.ifq.ai is appreciated. Please preserve the non-technical framing when quoting: the tutorial is intentionally written to be accessible to users with zero coding background, and should not be rewritten as a developer reference.

src/app/[locale]/page.tsx

@@ -10,7 +10,7 @@ import {
   HomeCTA,
 } from '@/components/home/HomeSections';
 import { StructuredData } from '@/components/StructuredData';
-import { SITE_URL } from '@/lib/routes';
+import { IFQ_URL, SITE_REPOSITORY_URL, SITE_URL } from '@/lib/routes';
 
 type Props = { params: Promise<{ locale: string }> };
 
@@ -28,6 +28,8 @@ export default async function HomePage({ params }: Props) {
       url: `${SITE_URL}/${locale}`,
       description: dict.meta.description,
       inLanguage: locale === 'zh' ? 'zh-CN' : 'en-US',
+      isAccessibleForFree: true,
+      license: 'https://opensource.org/license/mit',
       potentialAction: {
         '@type': 'SearchAction',
         target: `${SITE_URL}/${locale}/cases?q={query}`,
@@ -40,15 +42,32 @@ export default async function HomePage({ params }: Props) {
       name: dict.meta.siteName,
       url: SITE_URL,
       logo: `${SITE_URL}/favicon.svg`,
-      sameAs: ['https://openai.com', 'https://github.com'],
+      parentOrganization: {
+        '@type': 'Organization',
+        name: 'ifq.ai',
+        url: IFQ_URL,
+      },
+      sameAs: [IFQ_URL, SITE_REPOSITORY_URL, 'https://openai.com/codex'],
     },
     {
       '@context': 'https://schema.org',
       '@type': 'Course',
       name: dict.meta.siteName,
       description: dict.meta.description,
-      provider: { '@type': 'Organization', name: 'codex.ifq.ai' },
+      provider: { '@type': 'Organization', name: 'ifq.ai', url: IFQ_URL },
       inLanguage: [locale === 'zh' ? 'zh-CN' : 'en-US'],
+      isAccessibleForFree: true,
+      license: 'https://opensource.org/license/mit',
+      learningResourceType: ['Tutorial', 'Guide', 'Prompt generator', 'Case study'],
+      teaches: [
+        'OpenAI Codex desktop app basics',
+        'Prompt writing for non-developers',
+        'Local Windows and macOS desktop app workflows',
+      ],
+      audience: {
+        '@type': 'Audience',
+        audienceType: 'Non-developers and business teams',
+      },
       hasCourseInstance: [
         {
           '@type': 'CourseInstance',

src/app/layout.tsx

@@ -1,4 +1,6 @@
 import type { Metadata, Viewport } from 'next';
+import type { ReactNode } from 'react';
+import { Analytics } from '@/components/Analytics';
 import './globals.css';
 
 export const viewport: Viewport = {
@@ -8,11 +10,18 @@ export const viewport: Viewport = {
   ],
   width: 'device-width',
   initialScale: 1,
+  maximumScale: 5,
   viewportFit: 'cover',
 };
 
 export const metadata: Metadata = {
   metadataBase: new URL('https://codex.ifq.ai'),
+  applicationName: 'Codex Beginner Tutorial',
+  authors: [{ name: 'ifq.ai', url: 'https://ifq.ai' }],
+  creator: 'ifq.ai',
+  publisher: 'ifq.ai',
+  category: 'education',
+  classification: 'AI tutorial, Codex desktop, no-code desktop app, business automation',
   title: {
     default: 'Codex Beginner Tutorial · Codex 新手教程',
     template: '%s',
@@ -27,20 +36,83 @@ export const metadata: Metadata = {
     apple: '/apple-touch-icon.png',
   },
   manifest: '/manifest.webmanifest',
+  alternates: {
+    canonical: '/',
+    languages: {
+      'zh-CN': '/zh',
+      'en-US': '/en',
+      'x-default': '/',
+    },
+    types: {
+      'text/plain': [
+        { url: '/llms.txt', title: 'LLM Summary' },
+        { url: '/llms-full.txt', title: 'LLM Full Index' },
+      ],
+      'text/markdown': [
+        { url: '/agent.md', title: 'Agent Guide' },
+        { url: '/agents.md', title: 'Agents Guide' },
+      ],
+    },
+  },
   robots: {
     index: true,
     follow: true,
-    googleBot: { index: true, follow: true, 'max-snippet': -1, 'max-image-preview': 'large' },
+    googleBot: {
+      index: true,
+      follow: true,
+      'max-snippet': -1,
+      'max-image-preview': 'large',
+      'max-video-preview': -1,
+    },
+  },
+  openGraph: {
+    type: 'website',
+    url: 'https://codex.ifq.ai',
+    siteName: 'Codex Beginner Tutorial',
+    title: 'Codex Beginner Tutorial · Codex 新手教程',
+    description:
+      'Beginner-friendly OpenAI Codex desktop tutorial for non-developers — prompt generator, plain-language guide, and real department cases for Windows and macOS.',
+    images: [
+      {
+        url: '/og-image.svg',
+        width: 1200,
+        height: 630,
+        alt: 'Codex Beginner Tutorial',
+      },
+    ],
+  },
+  twitter: {
+    card: 'summary_large_image',
+    title: 'Codex Beginner Tutorial · Codex 新手教程',
+    description:
+      'Beginner-friendly OpenAI Codex desktop tutorial for non-developers — prompt generator, plain-language guide, and real department cases for Windows and macOS.',
+    images: ['/og-image.svg'],
   },
   other: {
     'format-detection': 'telephone=no',
+    'mobile-web-app-capable': 'yes',
+    'apple-mobile-web-app-capable': 'yes',
+    'apple-mobile-web-app-status-bar-style': 'default',
+    'llms-txt': 'https://codex.ifq.ai/llms.txt',
+    'llms-full': 'https://codex.ifq.ai/llms-full.txt',
+    'agent-guide': 'https://codex.ifq.ai/agent.md',
+    'ai-crawl': 'allow',
   },
 };
 
-export default function RootLayout({ children }: { children: React.ReactNode }) {
+export default function RootLayout({ children }: { children: ReactNode }) {
   return (
     <html lang="zh-CN" suppressHydrationWarning>
-      <body className="min-h-screen antialiased">{children}</body>
+      <head>
+        <link rel="alternate" type="text/plain" href="/llms.txt" title="LLM Summary" />
+        <link rel="alternate" type="text/plain" href="/llms-full.txt" title="LLM Full Index" />
+        <link rel="alternate" type="text/markdown" href="/agent.md" title="Agent Guide" />
+        <link rel="alternate" type="text/markdown" href="/agents.md" title="Agents Guide" />
+      </head>
+      <body className="min-h-screen antialiased">
+        {children}
+        <Analytics />
+      </body>
     </html>
   );
 }

src/app/robots.ts

@@ -1,5 +1,7 @@
 import type { MetadataRoute } from 'next';
 
+import { SITE_URL } from '@/lib/routes';
+
 export default function robots(): MetadataRoute.Robots {
   return {
     rules: [
@@ -11,22 +13,40 @@ export default function robots(): MetadataRoute.Robots {
       { userAgent: 'GPTBot', allow: '/' },
       { userAgent: 'ChatGPT-User', allow: '/' },
       { userAgent: 'OAI-SearchBot', allow: '/' },
+      { userAgent: 'Google-Extended', allow: '/' },
+      { userAgent: 'Gemini', allow: '/' },
       { userAgent: 'ClaudeBot', allow: '/' },
       { userAgent: 'Claude-Web', allow: '/' },
+      { userAgent: 'Claude-SearchBot', allow: '/' },
       { userAgent: 'anthropic-ai', allow: '/' },
       { userAgent: 'PerplexityBot', allow: '/' },
-      { userAgent: 'Google-Extended', allow: '/' },
+      { userAgent: 'YouBot', allow: '/' },
+      { userAgent: 'cohere-ai', allow: '/' },
+      { userAgent: 'Meta-ExternalAgent', allow: '/' },
+      { userAgent: 'Meta-ExternalFetcher', allow: '/' },
+      { userAgent: 'AI2Bot', allow: '/' },
+      { userAgent: 'Diffbot', allow: '/' },
+      { userAgent: 'Bytespider', allow: '/' },
       { userAgent: 'Googlebot', allow: '/' },
+      { userAgent: 'Googlebot-Image', allow: '/' },
       { userAgent: 'Bingbot', allow: '/' },
       { userAgent: 'Baiduspider', allow: '/' },
+      { userAgent: 'Sogou web spider', allow: '/' },
+      { userAgent: '360Spider', allow: '/' },
       { userAgent: 'Applebot', allow: '/' },
+      { userAgent: 'Applebot-Extended', allow: '/' },
       { userAgent: 'DuckDuckBot', allow: '/' },
       { userAgent: 'CCBot', allow: '/' },
       { userAgent: 'FacebookBot', allow: '/' },
       { userAgent: 'Amazonbot', allow: '/' },
+      { userAgent: 'Yandex', allow: '/' },
       { userAgent: 'YandexBot', allow: '/' },
+      { userAgent: 'Slurp', allow: '/' },
+      { userAgent: 'PetalBot', allow: '/' },
+      { userAgent: 'Timpibot', allow: '/' },
+      { userAgent: 'omgili', allow: '/' },
     ],
-    sitemap: 'https://codex.ifq.ai/sitemap.xml',
-    host: 'https://codex.ifq.ai',
+    sitemap: [`${SITE_URL}/sitemap.xml`, `${SITE_URL}/sitemap-index.xml`],
+    host: SITE_URL,
   };
 }