Website Content

Website Content

Write content for the site in the site owner's voice. The site splits content into two buckets:

• Site copy: Locale-scoped JSON only under content/locales/<locale>/site/*.json. The app loads these via src/lib/content.ts; there is no shared content/site/ source for home, about, or UI copy. Supported locales: en, es, zh (see src/lib/locales.ts).
• Writing and projects: MDX entries. For each locale, the app uses either that locale’s folder or the shared folder—not both. If content/locales/<locale>/writing exists, that locale sees only files in it; otherwise it uses content/writing. Same for projects: content/locales/<locale>/projects or else content/projects. Shared entries in content/writing and content/projects are the canonical default; use the content-translation skill to produce locale-specific copies after creating or updating them.

Before Writing

1. Read references/voice-guide.md to internalize the site owner's voice (customize that guide for your own voice if you forked this template).
2. Read references/content-schemas.md for the content type being written.
3. If updating homepage/about or other page-level copy, also read references/page-patterns.md.
4. For every new writing, investing, or project entry, read references/images.md and create a 16:9 raster feature image (.jpg or .png, not .svg) before finalizing the entry.

Content Types

Writing Entry (Essay / Quick Thought)

Choose the file location based on whether the piece is shared or locale-specific:

• Default/shared content: create or edit content/writing/[slug].mdx
• Locale-specific translation or locale-only piece: create or edit content/locales/<locale>/writing/[slug].mdx

Prefer the locale-specific path when the user explicitly wants translated or locale-specific writing. Use the shared path when the content is the canonical default entry consumed as fallback content.

After creating or updating a shared entry in content/writing/[slug].mdx, immediately read .agents/skills/content-translation/SKILL.md and use it to translate the finished entry into every other locale discovered under content/locales.

Frontmatter requirements (see content-schemas.md for full spec):

• title: evocative but honest; not clickbait
• publishDate: ISO 8601 datetime
• theme: reuse existing themes like Architecture, Developer Tools, Infrastructure, or Workflow when possible
• tags: 2-4 lowercase, specific tags
• ogImage: absolute site URL for the feature image, for example https://wchen.ai/writing/<slug>/feature.jpg
• featured: true only for foundational or especially important pieces
• draft: true for work-in-progress

For investing content, use theme: "Investing" and add the investing object described below.

Body guidelines:

• 200-1500 words
• No H1; the title renders from frontmatter
• Structure: provocation -> problem reframe -> position -> closing conviction
• Keep paragraphs short: 1-3 sentences
• Use italics sparingly for emphasis on key reframes
• End with a forward-looking conviction, not a summary
• Feature image: always create or source one as a 16:9 .jpg or .png (not .svg), save it under public/writing/<slug>/, set ogImage, and include the Markdown image in the body near the opening where it supports the narrative. For sourcing royalty-free images or using a user-provided image, read references/images.md. Mechanics (paths, syntax) in content-schemas.md.

Slug: derive from the core concept in lowercase kebab case, for example context-aware-agents.mdx.

Investing Entry (Stock Thesis / Portfolio Journal / Learning Note)

Investing entries are writing entries with theme: "Investing". They render under /investing and use investing-specific cards. Choose the entry kind before writing:

• Decision-oriented entries: stock-thesis, portfolio-journal, watchlist, postmortem, process-note
• Lightweight entries: learning, advice, habit

Use a Decision Record only when the entry makes or reviews an investment decision. Set showDecisionRecord: true and include thesis/invalidation/risk fields for stock theses, watchlist notes, postmortems, or decision-heavy portfolio journals. For learning, advice, habit, or general process notes, keep showDecisionRecord omitted or false and provide only kind plus summary unless more fields genuinely help.

Required investing frontmatter minimum:

theme: "Investing"
tags: ["investing", "portfolio", "public-journal"]
investing:
  kind: "learning" # stock-thesis | portfolio-journal | watchlist | postmortem | process-note | learning | advice | habit
  summary: "One concise sentence describing what this note helps inspect."

Decision-record frontmatter pattern:

investing:
  kind: "stock-thesis"
  showDecisionRecord: true
  ticker: "AAPL" # optional
  company: "Apple" # optional
  status: "watching" # watching | open | closed | review
  direction: "long" # long | short | neutral
  horizon: "6-18 months"
  disclosure: "No current position"
  summary: "The setup in one sentence."
  thesis: "What I believe the market is missing."
  invalidation: "What evidence would prove the thesis wrong."
  catalysts:
    - "Upcoming product cycle"
  decisionTriggers:
    - "Add if valuation compresses while thesis remains intact."
  risk: "The main way this can go wrong."
  lastReviewed: "2026-05-09T02:45:00Z"

Investing body guidelines:

• Always include a short disclaimer in the body for public stock/trading posts: Nothing here is financial advice.
• For stock theses: answer Why now?, What is the market missing?, What is already priced in?, What would make me add, trim, exit, or avoid?
• For learning/advice/habit posts: focus on the behavior, mistake pattern, or operating rule; do not force ticker, status, thesis, or invalidation fields.
• Avoid performance theater. Prefer decision quality, thesis integrity, review cadence, and mistake taxonomy over return bragging.
• Feature images for investing posts should use the high-contrast editorial thumbnail style in references/images.md: bold headline energy, market charts, red/green risk contrast, and clear visual framing around the trade, watchlist, or investing behavior.

Project Entry

Choose the file location based on whether the project entry is shared or locale-specific:

• Default/shared content: create or edit content/projects/[slug].mdx
• Locale-specific translation or locale-only entry: create or edit content/locales/<locale>/projects/[slug].mdx

Prefer the locale-specific path when the user asks for a translated or locale-only project entry. Use the shared path for the canonical default entry consumed as fallback content.

After creating or updating a shared entry in content/projects/[slug].mdx, immediately read .agents/skills/content-translation/SKILL.md and use it to translate the finished entry into every other locale discovered under content/locales.

Frontmatter requirements (see content-schemas.md for full spec):

• motivation: start with I wanted to... or I needed...
• problemAddressed: state the broken status quo vividly and concretely
• learnings: honest and specific; optional
• type: at least one of app, agent, experiment, skill, library, or tool
• status: active, archived, or in-progress
• ogImage: absolute site URL for the feature image, for example https://wchen.ai/projects/<slug>/hero.jpg

Body guidelines:

• Start with a brief context paragraph, then use structured H2 sections
• Common sections: How it works, The Vision, Architecture, Results
• Include code snippets only when they add real clarity
• Focus on narrative arc, not feature lists
• Feature image: always create or source one as a 16:9 .jpg or .png (not .svg), save it under public/projects/<slug>/, set ogImage, and include the Markdown image near the opening. For sourcing royalty-free images or using a user-provided image, read references/images.md. Mechanics (paths, syntax) in content-schemas.md.

Homepage Copy

Do not edit src/app/page.tsx; it is a locale redirect shell. Update locale content instead:

• Hero and section copy: content/locales/<locale>/site/home.json
• Shared identity and contact labels used on the page: content/locales/<locale>/site/profile.json

See page-patterns.md for the rendered section structure in src/app/[locale]/page.tsx.

Key constraints:

• Hero: intro plus two short supporting paragraphs
• Current Focus: short description plus two paragraphs
• A new visitor should understand who the site owner is, what they are building, and how to reach them within 15 seconds
• For route values like the about link, store the unprefixed path such as /about; localization is applied at runtime

About Page Copy

Do not edit src/app/about/page.tsx; it is a locale redirect shell. Update locale content instead:

• Page copy: content/locales/<locale>/site/about.json
• Shared CTA/contact strings used near the page: content/locales/<locale>/site/profile.json

See page-patterns.md for the rendered section structure in src/app/[locale]/about/page.tsx.

Key constraints:

• Philosophy: 3 paragraphs on core beliefs about building software
• Interests: 4 cards, each with a strong H3 topic and 1-2 sentence description
• Background: 3 paragraphs; tell the career arc as a story, not a resume
• Principles: 3 items, each with a short imperative phrase plus a one-sentence expansion

Shared Site Copy

All editable site copy lives under content/locales/<locale>/site/. Use these files when the request is not an MDX entry:

• content/locales/<locale>/site/profile.json: site identity, metadata defaults, nav labels, CTA copy, contact copy, not-found copy
• content/locales/<locale>/site/home.json: homepage hero and section copy
• content/locales/<locale>/site/about.json: about-page copy
• content/locales/<locale>/site/newsletter.json: newsletter email subjects, previews, button labels, recurring digest copy
• content/locales/<locale>/site/ui.json: shared UI strings (language switcher, theme toggle, share button, search, writing/project labels)
• content/locales/<locale>/site/forms.json: contact/newsletter form labels, placeholders, button copy
• content/locales/<locale>/site/system.json: validation, API, and fallback system messages

Do not edit content/site/newsletter-state.json for copy—it is managed by the recurring-newsletter build script and tracks which slugs have been sent.

Translation Handoff

Use the translation handoff only for shared MDX entries:

• Trigger it after finishing content/writing/[slug].mdx
• Trigger it after finishing content/projects/[slug].mdx
• Do not trigger it for content/locales/<locale>/... source files
• Do not trigger it for homepage, about, newsletter, UI, forms, or system JSON copy

Audio Publish Handoff

If the task creates or updates writing, investing, or project content that should have audio, do not assume generated audio is committed to Git.

Use this manual handoff after the content and any translations are finished:

1. Run pnpm audio:generate to create local audio artifacts under public/audio/ (writing, investing, or projects by content type).
2. Verify the affected page(s) locally if audio playback/highlighting matters to the task.
3. Run pnpm audio:publish to upload the generated assets and audio-manifest.json to R2.
4. Remind the user that production builds need AUDIO_SOURCE=r2 and R2_AUDIO_PUBLIC_BASE_URL configured.

Do not silently generate or upload audio as part of every content-writing task unless the user explicitly asks for that step.

Newsletter digest images

Every new writing, investing, and project entry should set ogImage to its feature image. When adding or changing ogImage on writing/project MDX (thumbnails in recurring digests), see docs/newsletter-digest-images.md. The site serves files from public/; CI mirrors eligible images to R2 with pnpm content-images:publish so digest emails do not 404 before deploy.

Voice Checklist

Run this check against every piece of content before finalizing:

• First person throughout when the content is narrative copy
• No corporate filler like leverage, synergy, innovative, cutting-edge
• No hedging language like kind of, sort of, maybe
• No exclamation points unless the user explicitly wants that tone
• No emojis in body copy
• Every paragraph advances one idea
• Paragraphs are 1-3 sentences when writing prose
• The ending lands on conviction, not recap
• New writing, investing, and project entries include a 16:9 .jpg or .png feature image file, body image reference, meaningful alt text, and ogImage
• Frontmatter or JSON shape matches the active schema (Zod in src/lib/schemas.ts; invalid content fails the build; see also scripts/validate-links.ts, validate-theme-descriptors.ts, validate-metadata.ts)

File Placement

public/
  writing/[slug]/                         -> Image assets for writing entry [slug]; feature images use 16:9 .jpg/.png, e.g. /writing/<slug>/feature.jpg
  projects/[slug]/                        -> Image assets for project entry [slug]; feature images use 16:9 .jpg/.png, e.g. /projects/<slug>/hero.png
content/
  writing/[slug].mdx                      -> Shared/default writing entries (canonical)
  projects/[slug].mdx                     -> Shared/default project entries (canonical)
  site/
    newsletter-state.json                 -> Script-managed; do not edit for copy
  locales/<locale>/site/                   -> Locales: en, es, zh
    profile.json                          -> Site identity, nav, CTA, metadata, contact, not-found
    home.json                             -> Homepage copy
    about.json                            -> About-page copy
    newsletter.json                       -> Newsletter email and flow copy
    ui.json                               -> Shared UI strings (share, search, theme, etc.)
    forms.json                            -> Form labels and placeholders
    system.json                           -> Validation and system messages
  locales/<locale>/writing/[slug].mdx     -> Locale-specific writing (used when present instead of shared)
  locales/<locale>/projects/[slug].mdx    -> Locale-specific projects (used when present instead of shared)
src/app/[locale]/
  page.tsx                                -> Homepage renderer
  about/page.tsx                          -> About-page renderer