Add detailed Claude.md and Cursor/rules

.cursor/rules.mdc

@@ -0,0 +1,245 @@
+---
+description: 
+globs: 
+alwaysApply: true
+---
+---
+description: Guidelines for contributing to Pulumi documentation and maintaining consistency across content, Hugo templates, and editor style
+globs: "**/*.md,**/*.html,**/*.js,**/*.ts,**/*.yaml,**/*.yml,**/*.json"
+alwaysApply: true
+---
+
+# Cursor Rules
+
+## Repository Overview
+
+- **Purpose:** Pulumi's Hugo-based documentation website at pulumi.com
+- **Technology Stack:** Hugo static site generator, Node.js/Yarn, TypeScript, Stencil web components, Tailwind CSS
+- **Content Types:** Documentation, blog posts, tutorials, examples, landing pages
+
+## Documentation Standards
+
+### **Language and Terminology**
+
+- Use `pulumi` or "the Pulumi CLI" to refer to the CLI
+- Use `Pulumi Cloud` to refer to the infrastructure management platform  
+- **Avoid ableist language:** Use "wild" instead of "crazy", "select" instead of "click", "placeholder" instead of "dummy"
+- **Avoid unnecessarily gendered language:** Use "folks", "y'all", or "everyone" instead of "guys"
+- **Avoid violent language** and pop-culture references
+- Use "navigate" instead of "go to"
+- Avoid directional words - link directly to sections
+- **Never use "easy" or "simple"** - they make assumptions about reader expertise
+
+### **Content Structure**
+
+- **One `h1` per page** - every page must have exactly one
+- **Heading hierarchy:** Only increment one level at a time (h2 → h3, never h2 → h4)
+- **Sentence case headings** for docs and registry (first letter capitalized only)
+- **Keep paragraphs short** - rarely use 4+ sentences
+- **Lead with engaging content**, end with exactly one call-to-action
+- **Use semantic line breaks** or keep paragraphs on single lines - **never reflow text**
+
+### **Links and References**
+
+- **Use descriptive link text** - avoid "here", "click here", "see here"
+- **Internal links:** Use standard Markdown syntax `[text](/path)` (migrating away from `{{< relref >}}`)
+- **External links:** Include full URLs with descriptive text
+- **Add redirects** via Hugo aliases when changing URLs: `aliases: [/old-path/]`
+
+### **Code and Examples**
+
+#### **Code Blocks**
+```typescript
+// ✅ DO: Use language-specific code fences with proper syntax highlighting
+const bucket = new aws.s3.BucketV2("my-bucket");
+
+// ❌ DON'T: Use generic code blocks without language specification
+```
+
+#### **Multi-Language Examples**
+
+- Store in `/static/programs/` following naming: `<program-name>-<language>`
+- Languages: `javascript`, `typescript`, `python`, `csharp`, `java`, `go`, `yaml`
+- Use `{{< example-program path="program-name" >}}` shortcode
+- Limit languages: `{{< example-program path="aws-s3" languages="typescript,python" >}}`
+
+#### **Code Snippets**
+
+- Use `{{< example-program-snippet path="program-name" language="typescript" from="10" to="20" >}}`
+- All examples must be complete, testable programs
+
+### **Hugo Shortcodes and Custom Components**
+
+#### **Language Choosers**
+```markdown
+{{< chooser "language" "typescript,python,go" >}}
+
+{{< choosable "language" "typescript" >}}
+TypeScript-specific content here
+{{< /choosable >}}
+
+{{< choosable "language" "python" >}}
+Python-specific content here  
+{{< /choosable >}}
+
+{{< /chooser >}}
+```
+
+#### **Notes and Alerts**
+```markdown
+{{% notes type="info" %}}
+Important information that's helpful but not critical
+{{% /notes %}}
+
+{{% notes type="tip" %}}
+Helpful ideas and best practices
+{{% /notes %}}
+
+{{% notes type="warning" %}}
+Critical information - bad things happen if missed
+{{% /notes %}}
+```
+
+#### **Video Embeds**
+```markdown
+{{< youtube "video-id?rel=0" >}}
+```
+
+- Always use `?rel=0` for Pulumi YouTube videos to limit suggested videos
+
+#### **Pulumi CLI Commands**
+
+- Use specific shortcodes for CLI references: `{{< pulumi-new >}}`, `{{< pulumi-apply >}}`, etc.
+- These auto-generate current CLI documentation
+
+### **Frontmatter Standards**
+
+#### **Required Fields**
+
+---
+title: "Page Title (60 char limit for SEO)"
+meta_desc: "SEO description"
+author: joe-duffy
+---
+
+#### **Extended Frontmatter**
+
+---
+title: "Short Title for SEO"
+allow_long_title: true  # Allows longer h1 display title
+meta_image: meta.png  # Social sharing image (1200x628 PNG)
+canonical_url: "https://canonical-source.com"  # For syndicated content
+authors:
+    - author-id
+tags:
+    - existing-tag-only  # Use existing tags, avoid creating new ones
+aliases:
+    - /old-url/
+    - /another-old-url/
+---
+
+#### **Blog-Specific Frontmatter**
+
+---
+date: 2024-01-15T10:00:00-07:00
+meta_image: meta.png
+authors:
+    - author-id
+tags:
+    - pulumi-news  # Company news
+    - aws  # Cloud providers (only major ones)
+    - features  # Feature announcements
+    - typescript  # Language-specific posts
+---
+
+### **File Organization**
+
+#### **Content Structure**
+
+- `/content/` - All Markdown content
+- `/content/blog/` - Blog posts with `_index.md` in subdirectories
+- `/content/docs/` - Documentation content
+- `/static/programs/` - Multi-language code examples
+- `/static/images/` - Images and assets
+
+#### **Layout Structure**
+
+- `/layouts/shortcodes/` - Custom Hugo shortcodes
+- `/layouts/partials/` - Reusable template components
+- `/theme/` - CSS/JS source files
+- `/assets/` - Built CSS/JS assets (checked in)
+
+### **Images and Media**
+
+#### **Blog Images**
+
+- Place images in same directory as blog post
+- Reference relatively: `![Alt text](image.png)`
+- **Social images:** 1200×628 PNG, opaque background
+- Use [Figma template](https://www.figma.com/file/TnD7nxjIxVvXq8w0W7awPG/Build-Your-Own-Meta-Image) for consistency
+
+#### **Animated GIFs**
+
+- Max 1200px wide, 3MB size limit
+- Optimize with Gifsicle: `gifsicle ./animation.gif --resize-width=1200 --optimize=3 --batch`
+
+#### **Team Images**
+
+- Add to `/static/images/team/`
+- Square JPG, 400x400 max, named with author ID
+
+### **Testing and Development**
+
+#### **Local Development**
+```bash
+make ensure     # Install dependencies
+make serve      # Development server (http://localhost:1313)
+make lint       # Check Markdown and formatting
+make format     # Auto-format files
+make test       # Test all example programs
+```
+
+#### **Code Example Testing**
+
+- All `/static/programs/` examples tested via `pulumi preview`
+- Include `Makefile` with `test` target for non-standard testing
+- Examples tested on every PR and nightly
+
+### **Common Hugo Patterns**
+
+#### **Conditional Content**
+
+```html
+{{ if .Params.show_section }}
+    <section>Content here</section>
+{{ end }}
+```
+
+#### **Loops and Data**
+
+```html
+{{ range .Params.items }}
+    <div>{{ .title }}</div>
+{{ end }}
+```
+
+#### **Partials and Includes**
+
+```html
+{{ partial "component-name.html" . }}
+```
+
+## Style Guide References
+
+- **Full Style Guide:** [STYLE-GUIDE.md](STYLE-GUIDE.md)
+- **Blogging Guide:** [BLOGGING.md](BLOGGING.md)  
+- **Code Examples:** [CODE-EXAMPLES.md](CODE-EXAMPLES.md)
+- **Contributing:** [CONTRIBUTING.md](CONTRIBUTING.md)
+
+## SEO and Search
+
+- **Algolia search** indexes: titles, descriptions, H2 headings, keywords, authors, tags
+- **Use strategic keywords** in titles, meta_desc, and H2 headings for discoverability
+- **Canonical URLs** required for syndicated content to avoid SEO penalties
+
+This repository powers one of the most comprehensive infrastructure-as-code documentation sites. Always prioritize **clarity, conciseness and accuracy** in content creation and maintenance.