Author

B. Talvinder

CLAUDE.md — talvinder.com site repo

This repository is the Quarto site only.

Scope

  • Edit site content, templates, styles, and GitHub workflow files in this repo
  • Do not modify engine code unless the Linear issue explicitly says the task is cross-repo
  • When a task spans both repos, stop and split the work if possible

Workflow

  • Linear is the planning surface
  • GitHub is the PR and review surface
  • Codex is preferred for well-scoped implementation tickets
  • Claude Code is preferred for review, local debugging, and ambiguous follow-up work

Expectations

  • One Linear issue should map to one branch and one PR
  • PRs should reference the Linear issue directly
  • Do not treat GitHub issues as a second backlog unless explicitly asked

Site-Specific Review Priorities

  1. Preserve Quarto build integrity
  2. Preserve existing visual language unless the issue asks for redesign
  3. Avoid breaking feeds, schema, metadata, or deploy workflows
  4. Prefer minimal HTML and SCSS changes over broad theme rewrites

Build Requirements

D2 diagrams are mandatory. The site uses D2 diagrams ({.d2} code blocks) rendered via the Quarto D2 extension. The d2 binary MUST be available at /opt/homebrew/bin/d2 (or on PATH) for every render. If D2 is not found, the render must fail — do NOT bypass, skip, remove, or work around D2 rendering. Fix the PATH or install D2. This is non-negotiable.

Required PATH for rendering: export PATH="$PATH:/opt/homebrew/bin"

Verification

When changing the site, prefer this verification order:

  1. Verify d2 is available: which d2 || echo "STOP: d2 not installed"
  2. quarto render (with full PATH including /opt/homebrew/bin)
  3. inspect the rendered output that changed
  4. if relevant, check deploy workflow assumptions in .github/workflows/deploy.yml

Notes

  • llms.txt, schema, feeds, and metadata are part of the site’s distribution surface
  • Homepage identity and engagement surfaces are strategy-critical, not cosmetic
  • Read DESIGN.md before changing the visual system or wordmark behavior
  • Read docs/information-architecture.md before changing navigation, page roles, or content hierarchy