diff --git a/README.md b/README.md index 08e1890..47bbf10 100644 --- a/README.md +++ b/README.md @@ -1,25 +1,32 @@ # Mist Architect -Mist Architect is the bilingual portfolio website for 岚·建筑设计 / MIST -Architects. The current build is intentionally lean: content is managed in code, -imagery is served from Alibaba Cloud OSS, and releases run on Alibaba Cloud ECS -as a Next.js standalone server. +Mist Architect is the developer repository for the bilingual portfolio website +of 岚·建筑设计 / MIST Architects. -## Stack +The site is a lean, code-managed Next.js application. Content lives in the +repository, images are served from Alibaba Cloud OSS, preview runs behind Basic +Auth, and production is manually promoted only after owner/client approval. -- Next.js App Router, React, and TypeScript -- Hand-authored global CSS with CSS variables -- `motion/react` for splash, menu, hero, and reveal motion -- GSAP ScrollTrigger plus Lenis for desktop scroll polish -- Alibaba Cloud OSS responsive image delivery with AVIF/WebP/JPG `` - output -- Playwright Chromium smoke tests -- GitHub Actions CI and protected preview deployment +## Jump To + +- [Project Purpose](#project-purpose) +- [Tech Stack](#tech-stack) +- [Getting Started](#getting-started) +- [Common Commands](#common-commands) +- [Repository Structure](#repository-structure) +- [SEO and Metadata](#seo-and-metadata) +- [Deployment Boundary](#deployment-boundary) +- [Contribution Workflow](#contribution-workflow) +- [Documentation Index](#documentation-index) + +## Project Purpose -The active build does not include a CMS, Sanity Studio, Tailwind, shadcn, or -React Bits runtime layer. +This repository contains the public website source for MIST Architects, including +localized routes, code-managed portfolio content, responsive OSS media helpers, +technical SEO files, GitHub Actions CI, and the protected preview deployment +workflow. -## Routes +Current public surfaces: ```text /zh @@ -35,15 +42,26 @@ React Bits runtime layer. ``` `field-academy` / WILD WORKSHOP is the only project with complete detail -material today. Other project detail pages intentionally show the project -cover image or carousel, a short in-development line, and a return link to the +material today. Other project detail pages intentionally show the project cover +image or carousel, a concise in-development state, and a return link to the project index. -The About contact section includes email, phone, office address, WeChat public -account, and WeChat Channels. Clicking the WeChat public account opens the QR -code stored at `public/20260531-191007.jpeg`. +The active build does not include a CMS/admin surface. Do not invent project +content, publication data, ICP filing numbers, or client-visible copy. -## Local Development +## Tech Stack + +- Next.js App Router, React, and TypeScript +- Hand-authored global CSS with CSS variables +- `motion/react` for splash, menu, hero, and reveal motion +- GSAP ScrollTrigger plus Lenis for desktop scroll polish +- Alibaba Cloud OSS responsive image delivery with AVIF/WebP/JPG `` + output +- Playwright Chromium smoke tests +- GitHub Actions CI and protected preview deployment +- Alibaba Cloud ECS, Nginx, and PM2 for preview/production runtime + +## Getting Started Use the project Node version through nvm: @@ -61,105 +79,175 @@ http://localhost:3000/zh http://localhost:3000/en ``` -## Verification +The first local Playwright run may need: -Before committing code changes: +```bash +npx playwright install chromium +``` + +## Common Commands ```bash +npm run dev npm run typecheck npm run lint +npm run build npm run test:e2e git diff --check ``` -Run `npm run build` when changes touch routing, Next.js config, media handling, -environment variables, or deployment behavior. - -The first local Playwright run may need: +Before committing code changes, run: ```bash -npx playwright install chromium +npm run typecheck +npm run lint +npm run test:e2e +git diff --check ``` -Local Playwright runs against the Next.js dev server. CI runs the same tests -against the standalone production server after `npm run build`. - -## Content and Media +Run `npm run build` when changes touch routing, Next.js config, media handling, +environment variables, or deployment behavior. Local Playwright runs against the +Next.js dev server; CI runs the same smoke tests against the standalone +production server after `npm run build`. -Site content is managed in: +## Repository Structure ```text -src/content/site.ts +AGENTS.md Agent rules and required read order +README.md First-stop developer overview +DESIGN.md Visual and interaction direction +docs/ Operations, SEO, deployment, and handoff docs +.github/workflows/ci.yml Pull request and main-branch verification +.github/workflows/deploy-preview.yml + Protected preview deployment workflow +src/app/ App Router routes, metadata, robots, sitemap +src/components/ Site UI components +src/content/site.ts Code-managed bilingual site content +src/lib/content.ts Content access adapter +src/lib/media.ts OSS/media URL and metadata image helpers +src/lib/seo.ts Canonical URLs, metadata, and JSON-LD helpers +tests/e2e/home.spec.ts Playwright smoke coverage +public/ Verification files, QR image, local font assets ``` -The content adapter is: +## SEO and Metadata -```text -src/lib/content.ts -``` +Technical SEO is code-owned in this repository, but search-engine indexing and +snippet refresh timing are outside direct code control. -Images referenced from code should use bucket-relative OSS paths and flow -through `src/lib/media.ts` / `src/components/oss-picture.tsx` where possible. -The active media origin is: +Maintain SEO in these files: ```text -https://mist-architects-media.oss-cn-shenzhen.aliyuncs.com +src/lib/seo.ts +src/app/[locale]/layout.tsx +src/app/[locale]/page.tsx +src/app/[locale]/about/page.tsx +src/app/[locale]/projects/page.tsx +src/app/[locale]/projects/[slug]/page.tsx +src/app/[locale]/journal/page.tsx +src/app/robots.ts +src/app/sitemap.ts +public/BingSiteAuth.xml +public/baidu_verify_codeva-rzwTLycS3q.html +public/f5775da6489b4079bb75b30bdd8fdbf9.txt ``` -`NEXT_PUBLIC_MEDIA_BASE` is supported as a future CDN/custom-origin override. -Leave it unset while the raw OSS origin is active. Do not switch to -`https://media.mist-arch.com` until Alibaba Cloud CDN, HTTPS, DNS, and the -Next image allow-list are changed together. +Current SEO principles: -## Environment +- canonical production host is `https://mist-arch.com` +- `/` permanently redirects to `/zh` +- localized routes expose canonical and `hreflang` alternates +- sitemap and robots are generated by Next.js route files +- Organization, WebSite, AboutPage, ContactPage, project, breadcrumb, and + WeChat-related JSON-LD live in `src/lib/seo.ts` +- search metadata image URLs should stay crawler-fetchable through the + site-owned media path described in `docs/SEO.md` +- preview must remain protected from indexing -Public variables: +See `docs/SEO.md` before changing metadata, verification files, sitemap, +robots, structured data, or search-engine submission behavior. + +## Deployment Boundary + +Persistent branches: ```text -NEXT_PUBLIC_SITE_URL -NEXT_PUBLIC_ICP_LICENSE +main +preview/home-featured-projects ``` -Optional media variables: +Public hosts: ```text -NEXT_PUBLIC_MEDIA_BASE -NEXT_PUBLIC_DISABLE_MEDIA_PROXY +https://mist-arch.com +https://preview.mist-arch.com ``` -Only set `NEXT_PUBLIC_ICP_LICENSE` after the real ICP filing value is provided. +Release flow: -## Release Workflow +1. Develop and verify locally. +2. Open a topic-branch pull request against `main`. +3. Let GitHub Actions CI pass. +4. After owner review, merge approved source to `main`. +5. Update `preview/home-featured-projects` to the exact reviewed commit. +6. Let GitHub Actions deploy the protected preview. +7. Promote the exact approved preview release to production only after approval. -Persistent branches: +Do not deploy an uncommitted local worktree, bypass preview approval, expose +secrets, change production, operate webmaster accounts, or use sensitive +credentials without explicit owner authorization. + +## Contribution Workflow + +Use a GitHub-native flow for non-trivial work: ```text -main -preview/home-featured-projects +GitHub Issue -> codex/* topic branch -> Pull Request -> GitHub Actions -> review/merge decision ``` -Release flow: +Issue descriptions should state the problem, scope, acceptance criteria, docs, +and tests. PR descriptions should link the issue and include scope, +verification, docs impact, risk/rollback, and owner decision needs. + +This is a formal client project. Keep changes scoped, preserve existing visual +and content direction, and prepare an approval brief before broad product, +visual, brand, copy, SEO-positioning, deployment, or customer-visible behavior +changes. + +## Documentation Index + +- `AGENTS.md` - entry rules, branch policy, and local verification. +- `docs/RELEASE_WORKFLOW.md` - Local -> Preview -> Production workflow. +- `docs/AGENT_HANDOFF.md` - current project, ECS, domain, OSS, and runtime + state. +- `DESIGN.md` - visual and interaction direction. +- `docs/CICD.md` - GitHub Actions, preview deploys, and production promotion. +- `docs/SEO.md` - metadata, sitemap, robots, structured data, verification + files, and search-engine submissions. +- `docs/IMAGE_PIPELINE.md` - OSS image processing, responsive images, CDN guard + rails, and metadata image behavior. +- `docs/DEPLOYMENT_PLAN.md` - Alibaba Cloud architecture decisions. +- `docs/DEVELOPMENT_LOG.md` - chronological implementation and deployment + history. +- `docs/GSAP_ANIMATIONS.md` - animation implementation notes. +- `docs/About.md` - supplemental project notes. -1. Develop and verify locally. -2. Commit the reviewed source on `main`. -3. Update `preview/home-featured-projects` to the exact reviewed commit and - push it. -4. Let GitHub Actions deploy the protected preview. -5. Promote the exact deployed preview release to production after approval. +## Environment -Preview and production: +Public variables: ```text -https://preview.mist-arch.com -https://mist-arch.com +NEXT_PUBLIC_SITE_URL +NEXT_PUBLIC_ICP_LICENSE ``` -See `docs/RELEASE_WORKFLOW.md`, `docs/CICD.md`, and -`docs/AGENT_HANDOFF.md` before changing deployment behavior. +Optional media variables: -## Project Notes +```text +NEXT_PUBLIC_MEDIA_BASE +NEXT_PUBLIC_DISABLE_MEDIA_PROXY +``` -- `AGENTS.md` is the entry file for coding agents. -- `DESIGN.md` defines the current visual and interaction direction. -- `docs/IMAGE_PIPELINE.md` documents OSS image processing and CDN guard rails. -- `docs/DEVELOPMENT_LOG.md` records implementation and deployment history. +Only set `NEXT_PUBLIC_ICP_LICENSE` after the real ICP filing value is provided. +Do not commit private webmaster tokens, Basic Auth credentials, SSH keys, or +production secrets. diff --git a/docs/DEVELOPMENT_LOG.md b/docs/DEVELOPMENT_LOG.md index 7085500..9bfb514 100644 --- a/docs/DEVELOPMENT_LOG.md +++ b/docs/DEVELOPMENT_LOG.md @@ -4,6 +4,37 @@ 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-06-19 / GitHub About and README Readability + +### Goals + +- Make the public GitHub repository easier for first-time developers to scan. +- Keep the work documentation-only and separate from the open SEO PR. + +### Changes + +- Created GitHub issue #4 to track the README/About metadata refresh. +- Updated GitHub About metadata: + - description: `Developer repository for the MIST Architects bilingual portfolio website.` + - homepage: `https://mist-arch.com` + - topics: `nextjs`, `react`, `typescript`, `architecture-portfolio`, + `bilingual-site`, `playwright`, `github-actions`, `alibaba-cloud` +- Reworked `README.md` with clearer positioning, Jump To links, project + purpose, tech stack, local setup, common commands, repository structure, + SEO/metadata maintenance notes, deployment boundary, contribution workflow, + documentation index, and environment notes. + +### Verification + +- `git diff --check`: passed. +- GitHub Actions CI is expected to run on the README PR. + +### Deployment + +- No website runtime UI change, SEO metadata change, visual direction change, + preview deploy, production deploy, Bing/Webmaster action, or production + credential/account operation was performed. + ## 2026-06-06 / Bing URL Inspection Follow-up ### Goals