Skip to content

CLAUDE.md

Latest commit

 

History

History
103 lines (81 loc) · 4.89 KB

CLAUDE.md

File metadata and controls

103 lines (81 loc) · 4.89 KB

Copilot Reader — Project Conventions

A research-website hub from the New Future of Work team at Microsoft Research.

The single architectural rule

Adding a post is a single-folder operation. Do not edit routes, the homepage, the registry source, or any shared file when adding a post. The registry auto-discovers via import.meta.glob in src/content/posts.ts. If a procedure tells you to edit one of those files to add a post, the procedure is wrong.

See CONTRIBUTING.md for the full Mode 1 (MDX in-repo) and Mode 2 (zip-import) recipes.

Stack

  • Vite 8 + React 19 + TypeScript 6 + Tailwind CSS v4
  • react-router-dom v7 (BrowserRouter, basename = import.meta.env.BASE_URL)
  • @mdx-js/rollup + @mdx-js/react (MDX 3)
  • Recharts 2.15, lucide-react
  • Self-hosted variable fonts via @fontsource-variable/{fraunces,inter,jetbrains-mono}
  • Engines: Node >=20.19. CI uses Node 22 LTS; local dev on Node 24 LTS.

Brand

The single source of truth is src/styles/globals.css. Tokens use oklch.

  • Surface/ink: bg-paper, bg-paper-warm, text-ink, text-ink-soft, text-ink-muted, border-rule, bg-highlight
  • Accents: bg-accent-1 through bg-accent-6
  • Charts: var(--color-chart-1) through var(--color-chart-5)

Editorial typography classes in src/styles/editorial.css: editorial-h1/-h2/-h3, editorial-lede, editorial-body, eyebrow, pull-quote, drop-cap, marker-highlight, hairline, reveal/reveal.in.

SEO / metadata

Use React 19 native metadata hoisting — render <title>, <meta>, <link> directly inside any component. React 19 deduplicates and hoists to <head> automatically. Do NOT add react-helmet-async; it doesn't support React 19 anyway. PostFrame.tsx is the canonical example.

Microsoft-org gotchas

These are policy constraints, not bugs. Codify, don't fight.

  • 🔒 Push procedure (working as of 2026-05-08): JIT v2 elevation + the right GitHub identity. While the repo's OSPO release review is in progress, activeRepoStatus stays "false" and standing-permission pushes are blocked. JIT v2 elevations bypass this freeze because they're time-bounded and audited — the intended mechanism.

    Step 1 — Use the FTE-bound GitHub account. At Microsoft, your EMU username is whatever the OSPO portal shows under Identity → "GitHub account" when signed in as your @microsoft.com email. For Alex Farach this is farach, NOT alexfarach_microsoft (the latter is a legacy username from a prior team and has no current FTE binding — gh CLI keeps it cached but it can't write to microsoft/ repos). Verify the active gh account:

    gh auth status        # active should be the FTE-bound name

    Step 2 — Invoke a JIT elevation in the OSPO portal. https://repos.opensource.microsoft.com/orgs/microsoft/repos/copilot-reader/jit → "Elevate" → fill justification → confirm. Self-elevation is currently allowed (will become approval-required in the future per Secure Future Initiative).

    Step 3 — Verify, push.

    gh api repos/microsoft/copilot-reader --jq '.permissions'
# expect "push": true (even while activeRepoStatus is "false" — that's fine)
git push

    Implication: batch your pushes. Each elevation window is a few hours; accumulate commits locally and push once.

  • Repo creation: gh repo create microsoft/<name> returns As an Enterprise Managed User, you cannot access this content. Use the GitHub web UI.

  • Workflow re-run / dispatch: gh run rerun and gh workflow run require admin rights. Trigger with a push instead.

  • Pages enablement: actions/configure-pages@v5 MUST run with enablement: false. Microsoft denies the workflow's GITHUB_TOKEN the pages:write scope. Enable Pages manually once via Settings → Pages → Source: GitHub Actions.

  • Auto-applied stub README: every new microsoft/ repo gets a "Repository setup required" README.md committed automatically. Rebase local commits with -X theirs to keep our content; do NOT force-push.

  • OSPO: complete the compliance flow at https://repos.opensource.microsoft.com/ before public launch.

  • gh accounts: this machine has both farach (personal) and alexfarach_microsoft. Switch with gh auth switch -u <name> before operations on microsoft/ repos. After switching, run gh auth setup-git so Git Credential Manager uses the new account's token (otherwise GCM caches the previous account and pushes fail with the wrong-user error).

Workspace path-with-spaces

Path is c:\Users\alexfarach\OneDrive - Microsoft\ai_and_prod\copilot_reader. Always quote in shell commands. Forward slashes work in most tooling.

Deploy

Push to main → GH Actions builds + deploys in ~30 s. Watch: gh run list --repo microsoft/copilot-reader --limit 3.