[codex] Tune About search snippet wording

AGENTS.md

@@ -16,6 +16,8 @@ Read these files in order before making changes:
    - `docs/IMAGE_PIPELINE.md` for OSS, responsive images, CDN, and image processing.
    - `docs/SEO.md` for search metadata, sitemap, robots, structured data,
      verification files, and search-engine submissions.
+   - `docs/GEO_PLAN.md` for AI-search visibility, crawler policy, `llms.txt`,
+     and citation monitoring.
    - `docs/DEPLOYMENT_PLAN.md` for Alibaba Cloud architecture decisions.
    - `docs/DEVELOPMENT_LOG.md` for chronological implementation history.
 

CONTEXT.md

@@ -0,0 +1,42 @@
+# Mist Architect Website Context
+
+This context defines project-specific language for the Mist Architect website,
+especially around search visibility and client-facing content decisions.
+
+## Language
+
+**Search Result Snippet**:
+The short summary text that a search engine shows below a result title, which may come from meta descriptions, visible page copy, or search-engine rewriting.
+_Avoid_: subtitle, Bing subtitle, fixed description
+
+**Meta Description**:
+The page-level metadata description exposed in HTML to suggest a search summary.
+_Avoid_: guaranteed search result text
+
+**Visible Intro Copy**:
+The concise public-facing introductory copy near the top of a page.
+_Avoid_: hidden SEO text, keyword block
+
+## Relationships
+
+- A **Meta Description** may influence a **Search Result Snippet**, but does not guarantee it.
+- A **Search Result Snippet** may be rewritten from **Visible Intro Copy** when the search engine considers the page text more relevant.
+- **Visible Intro Copy** is client-facing website content and requires owner approval before material wording changes.
+- Contact availability may be mentioned in a **Search Result Snippet**, but direct phone numbers, email addresses, and street addresses should remain on the contact page rather than being targeted for snippet display.
+- For `/zh/about` and `/en/about`, the desired **Search Result Snippet** direction is business-clear first: explain what the studio does before expressing brand atmosphere.
+- Chinese and English About summaries should stay semantically aligned, with the English page carrying a natural translation of the approved Chinese direction.
+- About summary wording should retain the founders, **Cheng Bo** and **Li Bo**, after the studio location and service focus rather than leading with founder identity.
+
+## Example dialogue
+
+> **Dev:** "Should we change the Search Result Snippet directly?"
+> **Domain expert:** "We cannot set it directly. We can adjust the Meta Description and, where approved, the Visible Intro Copy that Bing may use."
+
+## Flagged ambiguities
+
+- "副标题内容" was used for the red-box text in Bing results; resolved: this means **Search Result Snippet**, not page title, site name, sitelinks, or a guaranteed metadata field.
+- `/zh/about` visible introductory wording may be adjusted conservatively to influence the **Search Result Snippet**, but not as hidden SEO text or broad brand repositioning.
+- Contact information in search summaries was clarified: target wording may mention that contact details are available, but should not try to expose direct phone, email, or street address in the **Search Result Snippet**.
+- `/zh/about` and `/en/about` target summary tone was resolved as business-clear rather than primarily poetic or brand-atmospheric.
+- English About summary wording should reflect the updated Chinese direction rather than diverging into a different positioning.
+- Founder information was retained in the target About summary, but placed after the business/service description.

README.md

@@ -161,5 +161,6 @@ See `docs/RELEASE_WORKFLOW.md`, `docs/CICD.md`, and
 
 - `AGENTS.md` is the entry file for coding agents.
 - `DESIGN.md` defines the current visual and interaction direction.
+- `docs/GEO_PLAN.md` defines the AI-search / generative-engine visibility plan.
 - `docs/IMAGE_PIPELINE.md` documents OSS image processing and CDN guard rails.
 - `docs/DEVELOPMENT_LOG.md` records implementation and deployment history.

docs/AGENT_HANDOFF.md

@@ -98,6 +98,7 @@ DESIGN.md                              Visual and interaction direction
 docs/RELEASE_WORKFLOW.md              Local -> Preview -> Production flow
 docs/CICD.md                           GitHub Actions and deployment notes
 docs/SEO.md                            Technical SEO implementation and search submission notes
+docs/GEO_PLAN.md                       AI-search visibility, crawler policy, and citation monitoring
 docs/IMAGE_PIPELINE.md                 OSS image pipeline and CDN guard rails
 docs/DEPLOYMENT_PLAN.md                Alibaba Cloud architecture plan
 docs/DEVELOPMENT_LOG.md                Chronological implementation log

docs/DEVELOPMENT_LOG.md

@@ -4,6 +4,92 @@ This log is written for both human developers and future coding agents. Keep ent
 short, dated, and implementation-oriented so the next contributor can understand what
 changed, why it changed, how it was checked, and what remains open.
 
+## 2026-07-07 / GEO Foundation
+
+### Goals
+
+- Start the Generative Engine Optimization plan without changing the visible
+  site UI or inventing new project material.
+- Make public production pages easier for AI/search systems to identify,
+  summarize, and cite accurately.
+
+### Changes
+
+- Added `docs/GEO_PLAN.md` with crawler policy, `llms.txt` boundaries,
+  measurement queries, content priorities, and release checks.
+- Added root-served `public/llms.txt` as a concise canonical map for AI agents,
+  including key pages, core entities, citation boundaries, and crawler notes.
+- Expanded Organization JSON-LD with visible service scope, service catalog,
+  areas served, awards, and founder descriptions.
+- Expanded project JSON-LD with image arrays, project location, typology,
+  credit, visible fact properties, and section `hasPart` data for complete
+  project records.
+- Added project-index `CollectionPage` / `ItemList` JSON-LD and Journal
+  `CollectionPage` / `BlogPosting` JSON-LD for archive-level GEO discovery.
+- Made the Playwright local web server port configurable through
+  `PLAYWRIGHT_PORT` so e2e tests do not accidentally reuse another project on
+  port `3000`.
+- Allowed Next's generated `next-env.d.ts` route-type import to follow the
+  current `next typegen` output path.
+- Linked the new GEO plan from agent/readme/handoff documentation.
+- Added Playwright coverage for `llms.txt`, Organization GEO fields, and
+  project citation facts.
+
+### Verification
+
+- `npm run typecheck`: passed.
+- `npm run lint`: passed.
+- `npm run build`: passed.
+- `PLAYWRIGHT_PORT=3100 npm run test:e2e`: passed, 13 Chromium tests.
+- `git diff --check`: passed.
+- A default `npm run test:e2e` attempt initially reached another local project
+  already listening on port `3000`; the Playwright config now supports
+  `PLAYWRIGHT_PORT` for local collision-free runs.
+
+### Deployment
+
+- No preview deploy, production deploy, Bing/Webmaster action, or production
+  credential/account operation was performed.
+
+## 2026-07-07 / About Search Result Snippet Wording
+
+### Goals
+
+- Improve the likely Bing search result snippet for `/zh/about` after Bing
+  showed a snippet assembled from About navigation and visible intro text.
+- Keep the change conservative, owner-approved, and aligned across Chinese and
+  English About pages.
+
+### Changes
+
+- Added `CONTEXT.md` terms for Search Result Snippet, Meta Description, and
+  Visible Intro Copy so future SEO work does not treat Bing snippets as a
+  guaranteed metadata field.
+- Updated `/zh/about` metadata and visible intro copy with a business-clear
+  studio summary covering Shenzhen context, design scope, founders, project
+  archive, contact availability, and WeChat MIST-ARCH.
+- Updated `/en/about` metadata and visible intro copy with semantically aligned
+  English wording while keeping the metadata description within a Bing-friendly
+  length.
+- Preserved the boundary that direct phone numbers, email addresses, and street
+  addresses should not be targeted for search snippet display.
+- Added Playwright coverage for the About metadata and visible intro wording.
+- Updated `docs/SEO.md` with search result snippet guidance and expected About
+  description lengths.
+
+### Verification
+
+- `npm run typecheck`: passed.
+- `npm run lint`: passed.
+- `npm run build`: passed.
+- `npm run test:e2e`: passed, 9 Chromium tests.
+- `git diff --check`: passed.
+
+### Deployment
+
+- No preview deploy, production deploy, Bing/Webmaster action, or production
+  credential/account operation was performed.
+
 ## 2026-06-06 / Bing URL Inspection Follow-up
 
 ### Goals

docs/GEO_PLAN.md

@@ -0,0 +1,166 @@
+# Generative Engine Optimization Plan
+
+Last updated: 2026-07-07, Asia/Shanghai.
+
+This document defines the first GEO operating plan for `https://mist-arch.com`.
+It builds on `docs/SEO.md`; it does not replace classic technical SEO.
+
+## 1. Objective
+
+Make MIST Architects discoverable and accurately citable in AI-assisted search
+and answer engines while keeping the site calm, factual, bilingual, and aligned
+with the existing release workflow.
+
+Success means:
+
+- AI/search crawlers can access canonical production pages.
+- Public pages expose clear text, metadata, structured data, and internal links.
+- AI-generated answers can cite the studio, founders, services, contact
+  channels, and completed project facts without guessing.
+- Preview, localhost, credentials, and unpublished project material remain out
+  of public search surfaces.
+
+## 2. Current Baseline
+
+Implemented before this GEO plan:
+
+- Canonical production host: `https://mist-arch.com`.
+- Localized entries: `/zh` and `/en`, with `/` permanently redirecting to
+  `/zh`.
+- `robots.txt` allows public pages and disallows `/api/`.
+- `sitemap.xml` lists localized static pages and project detail routes.
+- Canonical URLs and `hreflang` alternates are generated from `src/lib/seo.ts`.
+- Organization, WebSite, AboutPage, ContactPage, ImageObject, project, and
+  breadcrumb JSON-LD are emitted.
+- Bing, Baidu, and IndexNow verification files are root-served from `public/`.
+- Preview remains Basic Auth protected and should stay non-indexable at the
+  infrastructure layer.
+
+First GEO-specific additions:
+
+- `public/llms.txt` gives AI agents a concise, public, canonical map of the
+  site and warns against citing preview or unpublished facts.
+- `src/lib/seo.ts` exposes richer Organization and project JSON-LD using
+  existing visible content: services, awards, areas served, project media,
+  location, credit, and fact properties.
+- Project index and Journal routes emit `CollectionPage` / `ItemList` /
+  `BlogPosting` JSON-LD so list surfaces are also machine-readable citation
+  entry points.
+
+## 3. Official Guidance Boundary
+
+Use official sources when changing crawler or AI-search behavior:
+
+- Google Search AI features: foundational SEO still applies; pages must be
+  indexable and eligible for snippets; no special AI-only markup is required.
+- OpenAI crawlers: `OAI-SearchBot` controls ChatGPT search visibility, while
+  `GPTBot` is a separate training-related control.
+- Bing Webmaster Tools AI Performance: use cited pages, grounding queries, and
+  page-level citation data as monitoring signals.
+- `llms.txt`: treat as an emerging, optional convention. It is useful as a
+  curated machine-readable site map, but it is not an access-control mechanism
+  and does not guarantee AI-search inclusion.
+
+## 4. Crawler Policy
+
+Current production intent:
+
+- Allow normal search indexing crawlers through the default `User-agent: *`
+  policy.
+- Keep `OAI-SearchBot` allowed so ChatGPT search features can discover public
+  production pages.
+- Do not add `GPTBot` or `Google-Extended` allow/disallow rules until the
+  project owner makes a specific content-use decision.
+- Keep preview blocked through Basic Auth and `X-Robots-Tag: noindex` at the
+  infrastructure layer.
+
+Decision needed from the project owner:
+
+- Whether public production content may be used for model training, or whether
+  training-related bots such as `GPTBot` and controls such as
+  `Google-Extended` should be disallowed while keeping search retrieval allowed.
+
+## 5. Content Strategy
+
+GEO content should stay visible, factual, and useful to human visitors.
+
+Priority pages:
+
+- `/zh/about` and `/en/about`: entity grounding for studio name, founders,
+  services, awards, publications, WeChat, and contact details.
+- `/zh/projects/field-academy` and `/en/projects/field-academy`: strongest
+  complete project record today.
+- `/zh/projects` and `/en/projects`: index-level project typology and location
+  discovery.
+
+Next content batch:
+
+1. Complete `dream-factory-experimental-theater` with verified site, concept,
+   material, program, drawing, credit, and media facts.
+2. Complete `wanzhi-natural-history-park` with verified exhibition, education,
+   circulation, and client/project facts.
+3. Complete `bambu-lab-first-store` with verified retail, technology showroom,
+   product experience, and event-space facts.
+4. Replace journal Unsplash placeholder images with OSS-hosted studio or
+   project imagery.
+5. Add real journal articles that answer likely discovery queries about public
+   cultural architecture, adaptive reuse, retail experience space, and studio
+   process.
+
+Do not auto-generate full project sections from short seed copy. A project
+should remain in the in-development fallback state until enough real material
+exists for a sectioned narrative.
+
+## 6. Measurement Plan
+
+Weekly manual checks:
+
+- Google Search Console: indexing, page experience, Search performance.
+- Bing Webmaster Tools: URL inspection, sitemap status, Site Scan, IndexNow,
+  and AI Performance when available.
+- Baidu Search Resource Platform: verification, indexing, and push state.
+- Production smoke checks for `/robots.txt`, `/sitemap.xml`, `/llms.txt`,
+  `/zh`, `/en`, `/zh/about`, `/en/about`, and key project pages.
+
+Representative GEO queries to track:
+
+- `岚建筑设计`
+- `MIST Architects`
+- `MIST-ARCH`
+- `深圳 建筑事务所 公共文化空间`
+- `Shenzhen architecture studio public cultural spaces`
+- `MIST Architects WeChat`
+- `岚建筑设计 公众号`
+- `WILD WORKSHOP Suzhou architect`
+- `苏州 钟家荡 原野学社 建筑师`
+
+Track:
+
+- Whether the answer cites `mist-arch.com`.
+- Which page is cited.
+- Whether the studio name, founders, services, location, and contact channels
+  are accurate.
+- Whether a non-production host or unpublished project claim appears.
+
+## 7. Release Checklist
+
+Before an SEO/GEO commit:
+
+```bash
+export NVM_DIR="$HOME/.nvm"
+. "$NVM_DIR/nvm.sh"
+npm run typecheck
+npm run lint
+npm run build
+npm run test:e2e
+git diff --check
+```
+
+After production promotion:
+
+- Smoke check `/robots.txt`, `/sitemap.xml`, and `/llms.txt`.
+- Submit changed production URLs through IndexNow.
+- Request inspection or indexing for changed high-value pages in Bing and
+  Google when appropriate.
+- Update `docs/DEVELOPMENT_LOG.md`; update release IDs only when preview or
+  production release IDs actually change.