myaidev-method 0.3.3 → 0.3.5

package/skills/payloadcms-publisher/SKILL.md

@@ -1,96 +1,160 @@
 ---
 name: payloadcms-publisher
-description: Publishes markdown content to PayloadCMS with Lexical rich text conversion and media handling. Use when publishing content to a PayloadCMS instance.
+description: Publishes markdown content to PayloadCMS with automatic Lexical rich text conversion, SEO metadata generation, and media uploads. Use when publishing content to a PayloadCMS instance, uploading articles to Payload CMS, or when the user mentions PayloadCMS publishing.
 argument-hint: "[file.md] [--status draft|published] [--collection posts] [--dry-run]"
-allowed-tools: [Read, Write, Edit, Bash, Glob, Grep]
+allowed-tools: [Read, Edit, Bash, Glob, Grep]
 disable-model-invocation: true
 ---
 
 # PayloadCMS Publisher
 
-You are a **PayloadCMS Publishing Agent** — converting markdown content to PayloadCMS Lexical rich text format and publishing via the REST API.
-
-## Arguments
-
-- `[file.md]` → Source markdown file (required)
-- `--status draft|published` → Publish status (default: draft)
-- `--collection <name>` → Target collection (default: posts)
-- `--id <doc-id>` → Update existing document
-- `--dry-run` → Validate without publishing
-- `--verbose` → Show detailed progress
-
-## Workflow
-
-1. **Read source file** — Parse frontmatter and markdown content
-2. **Load credentials** — Read from .env: `PAYLOADCMS_URL`, `PAYLOADCMS_EMAIL`, `PAYLOADCMS_PASSWORD`
-3. **Authenticate** — Login via `POST /api/users/login`
-4. **Convert markdown to Lexical:**
-   - Headings → heading nodes with proper levels
-   - Paragraphs → paragraph nodes with text children
-   - Lists → list nodes (ordered/unordered)
-   - Code blocks → code nodes with language
-   - Links → link nodes with URL
-   - Images → upload nodes (upload media first)
-   - Bold/italic → text nodes with format flags
-5. **Handle media:**
-   - Extract image references from content
-   - Upload images via `POST /api/media`
-   - Replace references with upload IDs
-6. **Publish:**
-   - New: `POST /api/{collection}`
-   - Update: `PATCH /api/{collection}/{id}`
-   - Set `_status` field based on --status flag
-7. **Report:** Document URL and ID
-
-## Lexical Format
-
-PayloadCMS uses Lexical editor format:
-```json
-{
-  "root": {
-    "type": "root",
-    "children": [
-      {
-        "type": "heading",
-        "tag": "h2",
-        "children": [{"type": "text", "text": "Title"}]
-      },
-      {
-        "type": "paragraph",
-        "children": [{"type": "text", "text": "Content"}]
-      }
-    ]
-  }
-}
+Publish markdown files to PayloadCMS via the bundled script. The script handles authentication, markdown-to-Lexical conversion, image uploads, and API calls.
+
+## Prerequisites
+
+Credentials in `.env`:
+
+```
+PAYLOADCMS_URL=https://your-payload-instance.com
+PAYLOADCMS_EMAIL=admin@example.com
+PAYLOADCMS_PASSWORD=your-password
 ```
 
-## Field Mapping
+Run `/myaidev-method:configure payloadcms` to set these up.
 
-| Frontmatter | PayloadCMS Field |
-|-------------|-----------------|
-| title | title |
-| meta_description | meta.description |
-| slug | slug |
-| tags | tags (relationship) |
-| category | category (relationship) |
-| featured_image | featuredImage (upload) |
+## Publishing workflow
 
-## Prerequisites
+Follow these steps in order.
+
+### Step 1: Read and validate the source file
 
-- PayloadCMS instance with REST API enabled
-- Credentials configured via `/configure payloadcms`
-- Target collection must exist in PayloadCMS schema
+Read the markdown file. Verify it has YAML frontmatter with at least a `title`. Stop if missing.
 
-## Error Handling
+### Step 2: Auto-populate missing fields
 
-- Auth failure → report credential issue, suggest `/configure payloadcms`
-- Collection not found → list available collections
-- Validation error → show which fields failed
-- Upload failure → publish without images, report which failed
+Inspect the frontmatter. For any of these fields that are **missing or empty**, generate them from the content body and write them into the frontmatter before publishing:
 
-## Script Integration
+| Field | How to generate | Max length |
+|-------|----------------|------------|
+| `slug` | Kebab-case from `title` | 80 chars |
+| `excerpt` | Summarize the article in 1-2 sentences. Capture the core value proposition. | 160 chars |
+| `meta.title` | SEO-optimized variation of `title`. Include primary keyword near the front. | 60 chars |
+| `meta.description` | Compelling search snippet. Include primary keyword, end with implicit CTA. | 155 chars |
+| `heroImage` | If the first element in the content body is a standalone image (`![alt](path)` on its own line), **promote** it: remove it from the body and note the path for hero image upload in Step 3. |  |
+
+**Do not overwrite** fields the user already set. Only fill gaps.
+
+After generating, write the updated frontmatter back to the file, then re-read to confirm.
+
+### Step 3: Upload hero image (if needed)
+
+If Step 2 identified a hero image to promote, upload it before publishing:
 
-Can invoke the publishing script for complex operations:
 ```bash
-node .myaidev-method/scripts/payloadcms-publish.js "article.md" --status draft
+node --input-type=module -e "
+import { PayloadCMSUtils } from '${CLAUDE_PLUGIN_ROOT}/src/lib/payloadcms-utils.js';
+const u = new PayloadCMSUtils(); await u.authenticate();
+const r = await u.uploadMedia('<hero-path>', '<hero-alt>');
+console.log(JSON.stringify({ id: r.doc?.id || r.id }));
+"
+```
+
+Substitute `<hero-path>` and `<hero-alt>` with the image path and alt text from the promoted image.
+
+Then set `heroImage` in frontmatter to the returned media ID.
+
+### Step 4: Dry run
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/src/scripts/payloadcms-publish.js" "<file>" --collection "<collection>" --status "<status>" --dry-run --json --verbose
+```
+
+Defaults: collection=`posts`, status=`draft`. Parse stdout as JSON. If `"success": false`, use the [error recovery table](#error-recovery) and stop.
+
+### Step 5: Publish
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/src/scripts/payloadcms-publish.js" "<file>" --collection "<collection>" --status "<status>" --json --verbose
+```
+
+Add `--id <id>` if updating an existing document.
+
+### Step 6: Report result
+
+```
+PayloadCMS Publish Result
+  Action:     created | updated
+  Document:   <document.id>
+  Collection: <document.collection>
+  Title:      <document.title>
+  Auto-generated: <list any fields you populated in Step 2>
+```
+
+## Script CLI reference
+
+Script: `${CLAUDE_PLUGIN_ROOT}/src/scripts/payloadcms-publish.js`
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `<file>` | Markdown file path (positional, or `--file`/`-f`) | Required |
+| `--collection`, `-c` | Target collection | `posts` |
+| `--status`, `-s` | `draft` or `published` | `draft` |
+| `--id` | Document ID for updates | New document |
+| `--dry-run` | Validate health + auth only | Off |
+| `--json` | Machine-readable JSON on stdout | Off |
+| `--verbose`, `-v` | Progress on stderr | Off |
+
+**Always pass `--json --verbose`**.
+
+## Markdown file format
+
+```markdown
+---
+title: My Article Title
+slug: my-article-title
+excerpt: A brief summary for listing pages.
+meta:
+  title: SEO Title - Primary Keyword
+  description: Compelling meta description with keyword and implicit CTA.
+heroImage: 64a1b2c3d4e5f6
+tags: [tag1, tag2]
+category: tutorials
+---
+
+Your article content here with **bold**, *italic*, `code`, [links](https://...), lists, headings, and code blocks.
+```
+
+Any frontmatter key maps directly to a PayloadCMS field. See [references/field-mapping.md](references/field-mapping.md) for all supported fields and patterns (hero images, SEO, excerpts, glossary, relationships).
+
+See [references/lexical-format.md](references/lexical-format.md) for Lexical conversion details and supported node types.
+
+## Error recovery
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `Failed to load PayloadCMS configuration` | Missing `.env` | Run `/myaidev-method:configure payloadcms` |
+| `PayloadCMS is not reachable` | Wrong URL or down | Check `PAYLOADCMS_URL` |
+| `Authentication failed (401)` | Bad credentials | Check email/password |
+| `HTTP 404` | Collection missing | Verify collection name |
+| `HTTP 400` | Validation error | Check required fields against schema |
+| `parseEditorState: type "X" not found` | Feature not enabled | Enable in Payload config: `BlocksFeature({ blocks: [CodeBlock()] })`, `ChecklistFeature()`, `TableFeature()` |
+| `Media upload failed` | File not found or rejected | Check image paths relative to markdown file |
+
+## Examples
+
+```bash
+# Publish as draft (auto-generates missing SEO fields)
+/myaidev-method:payloadcms-publisher article.md
+
+# Publish immediately
+/myaidev-method:payloadcms-publisher article.md --status published
+
+# Different collection
+/myaidev-method:payloadcms-publisher article.md --collection tutorials
+
+# Update existing
+/myaidev-method:payloadcms-publisher article.md --id 60d5ec49f8d2e
+
+# Dry run
+/myaidev-method:payloadcms-publisher article.md --dry-run
 ```

package/skills/payloadcms-publisher/references/field-mapping.md

@@ -0,0 +1,142 @@
+# PayloadCMS Field Mapping
+
+Frontmatter fields in the markdown source are mapped to PayloadCMS document fields by the publishing script.
+
+## Standard fields
+
+| Frontmatter Key | PayloadCMS Field | Type | Auto-populated | Notes |
+|-----------------|-----------------|------|----------------|-------|
+| `title` | `title` | string | No | Required — must be set by user |
+| `slug` | `slug` | string | Yes | Kebab-case from title, max 80 chars |
+| `excerpt` | `excerpt` | textarea | Yes | 1-2 sentence summary, max 160 chars |
+| `meta.title` | `meta.title` | string | Yes | SEO title with primary keyword, max 60 chars |
+| `meta.description` | `meta.description` | string | Yes | Search snippet with keyword + CTA, max 155 chars |
+| `heroImage` | `heroImage` | upload | Yes | Promoted from first content image if standalone |
+| `tags` | `tags` | relationship[] | No | Array of tag names or IDs |
+| `category` | `category` | relationship | No | Category name or ID |
+| `status` | `status` | string | No | Overridden by `--status` CLI flag |
+
+**Auto-populated** fields are generated by Claude during the publishing workflow (Step 2) when missing from frontmatter. User-provided values always take precedence.
+
+## How mapping works
+
+The script uses `gray-matter` to parse YAML frontmatter, then spreads all frontmatter fields directly into the PayloadCMS document payload:
+
+```yaml
+---
+title: My Post
+customField: some value
+nestedField:
+  subField: nested value
+---
+```
+
+Becomes:
+
+```json
+{
+  "title": "My Post",
+  "customField": "some value",
+  "nestedField": { "subField": "nested value" },
+  "content": { "root": { ... } },
+  "status": "draft"
+}
+```
+
+Any custom fields defined in your PayloadCMS collection schema can be set via frontmatter — the script passes them through as-is.
+
+## Hero image (featured image)
+
+PayloadCMS handles hero/featured images as a collection-level `upload` field — not inside the Lexical editor. This is the same pattern as WordPress featured images.
+
+```yaml
+---
+title: My Post
+heroImage: 64a1b2c3d4e5f6   # media document ID
+---
+```
+
+The field name depends on your collection schema (common names: `heroImage`, `featuredImage`, `image`, `hero.media`). Provide the media ID directly. If you need to upload first, use the `uploadMedia()` utility and reference the returned ID.
+
+For nested hero fields:
+
+```yaml
+---
+hero:
+  type: highImpact
+  media: 64a1b2c3d4e5f6
+---
+```
+
+## SEO / Meta fields
+
+If your PayloadCMS instance uses `@payloadcms/plugin-seo`, SEO fields are collection-level (not Lexical nodes). The plugin adds a `meta` group field:
+
+```yaml
+---
+title: My Post
+meta:
+  title: SEO Title Override
+  description: Meta description for search engines
+  image: 64a1b2c3d4e5f6   # media ID for og:image
+---
+```
+
+If your schema uses flat field names instead (no plugin), adjust accordingly:
+
+```yaml
+---
+meta_title: SEO Title
+meta_description: Meta description
+---
+```
+
+## Excerpt
+
+Excerpts are typically a plain `textarea` field on the collection, not part of the Lexical editor:
+
+```yaml
+---
+title: My Post
+excerpt: A brief summary of the article shown in listing pages and social cards.
+---
+```
+
+## Glossary
+
+PayloadCMS has no built-in glossary feature. Glossaries are implemented as either:
+
+1. **A separate `glossary` collection** with `term` and `definition` fields — reference terms via a relationship field on your post:
+
+```yaml
+---
+glossaryTerms: [term-id-1, term-id-2]
+---
+```
+
+2. **A custom Lexical block** via `BlocksFeature` — these are rendered inside the rich text editor but require a custom block definition on the PayloadCMS instance. The markdown converter cannot produce custom blocks; they must be injected programmatically after conversion.
+
+## Relationship fields
+
+Tags and categories are typically relationship fields in PayloadCMS. Provide either:
+- **Names** (if your schema has a `name` field): `tags: [javascript, tutorial]`
+- **IDs** (for direct references): `tags: [abc123, def456]`
+
+The exact behavior depends on your PayloadCMS collection schema configuration.
+
+## Media uploads (in content body)
+
+The publishing script automatically uploads images referenced in the markdown content body. During `publishContent()`:
+
+1. `<div class="infographic" ...>` and `</div>` wrapper lines are stripped
+2. Standalone `![alt](path)` image lines are detected
+3. Each image file is uploaded to `/api/media` via `uploadMedia()`
+4. The image reference is replaced with an `upload` Lexical node pointing to the media ID
+
+Image paths are resolved relative to the markdown file's directory. If an image file doesn't exist or upload fails, a warning is logged and the image markdown is left as-is (rendered as text).
+
+Media referenced in frontmatter fields (e.g. `heroImage`) is **not** auto-uploaded — provide a media ID directly for those fields.
+
+## Inline images
+
+PayloadCMS Lexical does **not** support inline images. The `UploadNode` is block-level only (`isInline()` returns `false`). Images in content are always rendered as standalone blocks between paragraphs, never inline with text. This is a Lexical architecture constraint, not a limitation of this script.

package/skills/payloadcms-publisher/references/lexical-format.md

@@ -0,0 +1,97 @@
+# PayloadCMS Lexical Rich Text Format
+
+PayloadCMS uses the Lexical editor by default. The publishing script converts markdown to Lexical JSON automatically via `convertMarkdownToLexical()` in `payloadcms-utils.js`, which uses a headless Lexical editor with PayloadCMS's own node classes and markdown transformers from `@payloadcms/richtext-lexical`.
+
+## Root structure
+
+```json
+{
+  "root": {
+    "type": "root",
+    "format": "",
+    "indent": 0,
+    "version": 1,
+    "children": [ ... ],
+    "direction": null
+  }
+}
+```
+
+## Supported node types
+
+| Markdown | Lexical Node | Key Properties |
+|----------|-------------|----------------|
+| `# Heading` | `heading` | `tag: "h1"` through `"h6"` |
+| Paragraph text | `paragraph` | `children: [text nodes]`, `textFormat`, `textStyle` |
+| `- list item` | `list` + `listitem` | `listType: "bullet"` or `"number"`, `tag: "ul"` or `"ol"` |
+| `> blockquote` | `quote` | Wraps text children directly |
+| `---` | `horizontalrule` | DecoratorNode, no children |
+| `[link](url)` | `link` | `fields: { url, linkType, newTab }`, `version: 3` |
+| `\| col \| col \|` | `table` > `tablerow` > `tablecell` | `headerState: 0\|1`, `colSpan`, `rowSpan` |
+| `![alt](path)` | `upload` | `relationTo: "media"`, `value: "<media-id>"`, `id: "<node-id>"`, `fields: {}`, `version: 3` |
+| `` ```lang `` | `block` | `fields: { blockType: "Code", code, language, id }`, `version: 2` |
+| `- [ ] item` | `list` + `listitem` | `listType: "check"`, `checked: true\|false` |
+
+Code blocks (triple backticks) are converted to PayloadCMS `block` nodes with `blockType: "Code"` via the premade CodeBlock feature. The `language` field captures the language tag and `code` contains the block content. The PayloadCMS instance must have `BlocksFeature({ blocks: [CodeBlock()] })` enabled to render these blocks.
+
+Checklists (`- [ ]` / `- [x]`) produce `list` nodes with `listType: "check"`. Each `listitem` has a `checked` boolean. The PayloadCMS instance must have `ChecklistFeature()` enabled.
+
+Images (`![alt](path)`) are handled during `publishContent()` — the file is uploaded to the `media` collection first, then an `upload` node referencing the media ID is injected into the Lexical JSON. Upload nodes require both an `id` (unique node identifier, not the media document ID) and a `fields` object (can be empty `{}`). Without these, the PayloadCMS frontend renderer fails to display the image in preview. Tables require the `EXPERIMENTAL_TableFeature` to be enabled on the PayloadCMS instance.
+
+## Text formatting (bitwise flags)
+
+Inline formatting uses Lexical's bitwise format codes:
+
+| Format | Code | Markdown |
+|--------|------|----------|
+| Plain | `0` | `text` |
+| Bold | `1` | `**text**` |
+| Italic | `2` | `*text*` |
+| Bold + Italic | `3` | `***text***` |
+| Strikethrough | `4` | `~~text~~` |
+| Underline | `8` | N/A |
+| Code | `16` | `` `text` `` |
+| Subscript | `32` | N/A |
+| Superscript | `64` | N/A |
+| Highlight | `128` | `==text==` |
+
+Formats combine via bitwise OR. For example, bold italic code = `1 | 2 | 16 = 19`.
+
+## Text node structure
+
+```json
+{
+  "type": "text",
+  "text": "Hello world",
+  "format": 0,
+  "mode": "normal",
+  "style": "",
+  "detail": 0,
+  "version": 1
+}
+```
+
+## Coverage: markdown-producible vs non-markdown nodes
+
+The converter handles **every Lexical node type that can be produced from markdown input**. The table above is the complete set.
+
+PayloadCMS's default Lexical editor also registers these node types, which are **not producible from markdown** and therefore not part of this conversion pipeline:
+
+| Node | Purpose | How to use |
+|------|---------|------------|
+| `relationship` | Embed a reference to another collection document | Programmatic only — use `RelationshipServerNode` |
+| `autolink` | Auto-detected URLs in editor typing | Client-side only — never produced from markdown |
+
+These nodes exist for interactive editor use and API round-tripping, not markdown conversion.
+
+### What about hero images, SEO, excerpts?
+
+These are **collection-level fields**, not Lexical editor nodes. They're set via frontmatter and passed through to the PayloadCMS API payload. See [field-mapping.md](field-mapping.md) for details.
+
+### Inline images
+
+PayloadCMS Lexical does not support inline images. `UploadNode` is block-level only. Images are always rendered as standalone blocks between paragraphs.
+
+## Validation
+
+The converter uses Lexical's own serialization (`editor.getEditorState().toJSON()`), so the output is guaranteed to be structurally valid. No separate validation step is needed — the JSON is identical to what PayloadCMS's editor produces.

package/skills/security-auditor/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: security-auditor
 description: Performs security compliance audits and code security reviews against industry standards (OWASP, SOC2, HIPAA, PCI-DSS). Use when auditing code for security vulnerabilities, checking compliance, or generating security reports.
-argument-hint: [path] [--standard=owasp]
+argument-hint: "[path] [--standard=owasp]"
 allowed-tools: [Read, Glob, Grep, Task, WebSearch]
 ---