claude-plugin-wordpress-manager 2.12.2 → 2.14.0

package/skills/wp-dashboard/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: wp-dashboard
+description: This skill should be used when the user asks to "show dashboard",
+  "show editorial status", "open kanban", "visualize content state",
+  "show content overview", "mostra dashboard", "apri kanban", "stato editoriale",
+  "dove siamo con i post", or wants a visual overview of the editorial pipeline.
+  Generates a self-contained HTML Kanban board from .content-state/ files
+  and opens it in the browser.
+version: 1.0.0
+---
+
+# WordPress Dashboard Skill
+
+## Overview
+
+Generates a self-contained HTML Kanban dashboard from `.content-state/` files and opens it in the default browser. The dashboard provides a visual overview of the editorial pipeline — all content entries grouped by lifecycle status (planned, draft, ready, scheduled, published) — plus aggregate metrics and active signals.
+
+The HTML file has zero external dependencies. It reads the same `.content-state/` files used by `wp-content-pipeline` and `wp-editorial-planner`, computes aggregate metrics, and renders a static report.
+
+## When to Use
+
+- User wants to see the overall editorial status before starting work
+- User asks "dove siamo con i post?" or "show me the editorial status"
+- User wants to share a visual overview with stakeholders
+- Before a planning session (to identify gaps in the calendar)
+- After a publishing session (to confirm progress)
+- When investigating why content is stuck in a particular status
+
+## Workflow
+
+### Step 1: Determine Target Site
+
+- If the user specifies a site → use it
+- If only one `.config.md` exists in `.content-state/` → use that site automatically
+- If multiple sites exist → ask the user which site to visualize
+
+### Step 2: Determine Target Month
+
+- Default: the most recent editorial calendar found in `.content-state/`
+- If the user specifies a month → use `--month=YYYY-MM`
+
+### Step 3: Generate Dashboard
+
+Run the renderer script:
+
+```bash
+node scripts/dashboard-renderer.mjs --site={siteId}
+```
+
+Optional flags:
+- `--month=YYYY-MM` — specific month
+- `--output=/path/to/file.html` — custom output path
+- `--no-open` — generate HTML without opening browser
+
+The script will:
+1. SCAN `.content-state/` files (config, calendar, briefs, signals)
+2. AGGREGATE metrics (progress, pipeline counts, fill rate, next deadline)
+3. RENDER self-contained HTML Kanban
+4. Write to `.content-state/.dashboard-{site}-{month}.html`
+5. Open in default browser
+
+### Step 4: Report to User
+
+After generation, report:
+- File path and size
+- Key metrics: posts published/target, pipeline status, signals count
+- Suggest next actions based on what the dashboard reveals
+
+## Reading the Dashboard
+
+### Kanban Columns
+
+| Column | Meaning | Next Action |
+|--------|---------|-------------|
+| **Planned** | Calendar slot exists, no brief yet. Grey cards may have no title. | Assign topics, create briefs → `wp-editorial-planner` BRIEF step |
+| **Draft** | Brief created, content being written. | Fill brief content, then set `status: ready` |
+| **Ready** | Content validated, waiting for scheduling. | Schedule to WordPress → `wp-editorial-planner` SCHEDULE step |
+| **Scheduled** | WordPress future post created, waiting for publish date. | Wait, or run SYNC to check status |
+| **Published** | Live on WordPress. Green border, shows WP post ID. | Distribute to channels → `wp-content-pipeline` DISTRIBUTE step |
+
+### Card Elements
+
+- **Date**: target publish date from the editorial calendar
+- **Title**: content title (or `[da assegnare]` for unassigned slots)
+- **Brief ID**: `BRF-YYYY-NNN` identifier linking to the brief file
+- **WP #ID**: WordPress post ID (only for scheduled/published)
+- **Channel badges**: colored pills showing distribution channels (in=LinkedIn, tw=Twitter, nl=Newsletter, bf=Buffer)
+
+### Progress Bar
+
+Shows `published / target` ratio. The target comes from the calendar's `goals.posts_target`.
+
+### Signals Strip
+
+Shows anomalies from `signals-feed.md` with delta percentage, entity, and suggested action. Only appears if signals data exists.
+
+## Next Actions by Observation
+
+| What You See | What To Do | Skill |
+|-------------|------------|-------|
+| Empty "Planned" slots | Assign topics from signals or strategy | `wp-editorial-planner` PLAN |
+| Planned entries without briefs | Convert to briefs | `wp-editorial-planner` BRIEF |
+| Many entries stuck in "Draft" | Fill content in brief files | Manual editing |
+| "Ready" entries waiting | Schedule to WordPress | `wp-editorial-planner` SCHEDULE |
+| "Scheduled" not moving to "Published" | Run sync check | `wp-editorial-planner` SYNC |
+| High-delta signals | Investigate and create content | `wp-analytics`, `wp-search-console` |
+| Low fill rate (<50%) | Plan more content | `wp-editorial-planner` PLAN |
+
+## Safety Rules
+
+- This skill is **read-only**: it reads `.content-state/` files but never modifies them
+- The generated HTML is an ephemeral artifact — regenerate anytime for fresh data
+- Dashboard files are gitignored (`.content-state/.dashboard-*.html`)
+- No external network calls are made during generation
+
+## Related Skills
+
+- **`wp-editorial-planner`** — manages the editorial calendar that feeds the dashboard
+- **`wp-content-pipeline`** — processes briefs shown in the Kanban cards
+- **`wp-analytics`** — generates the signals feed shown in the signals strip
+- **`wp-search-console`** — contributes search data to the signals feed

package/skills/wp-deploy/references/ssh-deploy.md

@@ -47,10 +47,10 @@ ssh user@host 'rm /tmp/theme-name.tar.gz'
 ## SSH Config for Hostinger
 
 ```
-Host opencactus-hostinger
+Host mysite-hostinger
     HostName <ip-or-hostname>
     User <hostinger-username>
-    IdentityFile ~/.ssh/hostinger_opencactus_20250904
+    IdentityFile ~/.ssh/hostinger_mysite_20250904
     IdentitiesOnly yes
 ```
 

package/skills/wp-editorial-planner/SKILL.md

@@ -0,0 +1,262 @@
+---
+name: wp-editorial-planner
+description: This skill should be used when the user asks to "create an editorial
+  plan", "update the calendar", "schedule posts", "plan content for March",
+  "convert calendar to briefs", "sync calendar with WordPress", "show editorial
+  status", or mentions planning content over time. Orchestrates monthly editorial
+  calendars that bridge signals intelligence to content publishing.
+version: 1.0.0
+---
+
+# WordPress Editorial Planner Skill
+
+## Overview
+
+The editorial planner manages monthly content calendars as `.state.md` files stored in `.content-state/`. It reads site configuration for publishing cadence, optionally consumes the signals feed generated by `wp-analytics` for data-driven topic ideas, and produces structured briefs that flow into the content pipeline for WordPress publishing. The workflow follows four sequential steps: **PLAN** (create or update the monthly calendar), **BRIEF** (convert planned entries into pipeline brief files), **SCHEDULE** (create WordPress future posts from ready briefs), and **SYNC** (synchronize WordPress publish status back to the calendar). Each step is idempotent and can be run independently.
+
+## When to Use
+
+- User wants to create a new monthly editorial plan
+- User asks to update or view the current calendar
+- User wants to convert planned entries into content briefs
+- User asks to schedule ready briefs as WordPress future posts
+- User wants to sync WordPress publish status back to the calendar
+- User mentions "piano editoriale", "calendario", "schedula"
+
+## Workflow Overview
+
+```
+PLAN --> BRIEF --> SCHEDULE --> SYNC
+```
+
+---
+
+## Step 1: PLAN -- Create or update editorial calendar
+
+**When to run:** User asks to create a new plan or update an existing one.
+
+**Procedure:**
+
+1. **Read site configuration** from `.content-state/{site_id}.config.md`:
+   - `cadence.posts_per_week` -- calculate `goals.posts_target` as `posts_per_week * weeks_in_month`
+   - `cadence.preferred_days` -- determine which weekdays to assign calendar entries
+   - `cadence.publish_time` -- note for the SCHEDULE step
+   - `defaults.categories`, `defaults.content_type` -- pre-fill the entry Tipo column
+
+2. **Read signals feed** from `.content-state/signals-feed.md` if it exists:
+   - Extract anomalies with action containing "content cluster" or "Investigate"
+   - Suggest these as topics for `[da assegnare]` entries
+   - Present suggestions to user for approval before inserting into the calendar
+
+3. **Optional strategic planning:** If the user wants a higher-level content strategy, suggest invoking GenMarketing for content calendar strategy development before populating individual entries.
+
+4. **Generate or update** `.content-state/{YYYY-MM}-editorial.state.md`:
+   - Create YAML frontmatter with `calendar_id`, `site_id`, `period`, `goals`
+   - Create weekly tables with one row per `preferred_day`
+   - Fill known titles where provided, leave others as `[da assegnare]`
+   - Set all new entries as `status: planned`
+
+5. **Present the calendar** to the user for review before writing to disk.
+
+**Safety rules:**
+- ALWAYS show the generated calendar to the user before writing the file
+- If a calendar for the month already exists, show the diff and ask before overwriting
+- Preserve existing entries that have `status: draft` or higher -- never reset them to `planned`
+
+---
+
+## Step 2: BRIEF -- Convert calendar entries to brief files
+
+**When to run:** User asks to "create briefs from calendar" or "convert planned entries to briefs".
+
+**Procedure:**
+
+1. Read the current editorial calendar `.state.md` file.
+
+2. For each entry with `status: planned` AND a defined title (not `[da assegnare]`):
+   a. Generate a new `brief_id` as `BRF-YYYY-NNN` (sequential; scan existing briefs in both `pipeline-active/` and `pipeline-archive/` to determine the next number)
+   b. Read `.content-state/{site_id}.config.md` for site defaults
+   c. Create `.content-state/pipeline-active/{brief_id}.brief.md` with:
+      - `source.skill: wp-editorial-planner`
+      - `source.domain: editorial-calendar`
+      - `target.site_id`: from calendar `site_id`
+      - `target.content_type`: from entry Tipo column
+      - `target.scheduled_date`: from entry Data column (convert to ISO 8601)
+      - `target.categories`: from site config defaults
+      - `distribution.channels`: from entry Canali column (parse comma-separated)
+      - `content.title`: from entry Titolo column
+      - `status: draft` (brief starts as draft; user fills content)
+   d. Update the calendar entry: `status: planned` becomes `draft`, set the Brief ID column
+
+3. For entries with an existing Brief ID (already has a brief): skip creation, just verify the brief file exists in `pipeline-active/`. If the file is missing, report it.
+
+4. Write the updated calendar back to the `.state.md` file.
+
+5. Report to user:
+   ```
+   N brief creati in pipeline-active/. Compila il contenuto e imposta status: ready.
+   ```
+
+**Safety rules:**
+- NEVER create briefs for entries with `[da assegnare]` title -- report them as needing titles first
+- NEVER overwrite existing brief files -- if a Brief ID already exists as a file, skip and report
+- Show a summary of briefs to be created and ask user confirmation before writing any files
+
+---
+
+## Step 3: SCHEDULE -- Convert ready briefs to WordPress scheduled posts
+
+**When to run:** User asks to "schedule ready posts" or "schedula i post pronti".
+
+**Procedure:**
+
+1. Read the current editorial calendar `.state.md` file.
+
+2. For each entry with `status: ready`:
+   a. Read the corresponding brief file from `pipeline-active/{brief_id}.brief.md`
+   b. Verify the brief has `status: ready` (consistency check between calendar and brief)
+   c. Create the WordPress post using MCP tool:
+      ```
+      create_content:
+        content_type: {entry.Tipo}
+        title: {brief.content.title}
+        content: {brief body markdown}
+        excerpt: {brief.content.excerpt}
+        status: "future"
+        date: {entry.Data as ISO 8601 datetime with site config publish_time}
+        slug: {auto-generated from title}
+      ```
+   d. Assign taxonomy terms using MCP tool:
+      ```
+      assign_terms_to_content:
+        content_type: {entry.Tipo}
+        id: {post_id}
+        categories: {brief.target.categories}
+        tags: {brief.target.tags}
+      ```
+   e. Update the calendar entry: `status: ready` becomes `scheduled`, set Post ID column
+   f. Update the brief file: add `post_id` and `post_url` to frontmatter
+
+3. If the entry has `distribution.channels` (from the Canali column):
+   - Compute `scheduled_at` using the entry date + `config.cadence.publish_time` + `distribution.schedule_offset_hours`
+   - For Buffer: call `buf_create_update` with the computed `scheduled_at`
+     ```
+     buf_create_update:
+       profile_ids: [{config.channels.buffer.profile_id}]
+       text: {adapted content}
+       media:
+         photo: {featured image URL if available}
+       scheduled_at: {ISO 8601 UTC timestamp}
+     ```
+   - For Mailchimp: note for manual campaign creation (not auto-scheduled at this step)
+
+4. Write the updated calendar back to the `.state.md` file.
+
+5. Report to user:
+   ```
+   N post schedulati su WordPress. Verranno pubblicati automaticamente alla data prevista.
+   ```
+
+**Safety rules:**
+- ALWAYS create WordPress posts as `status: future` (never directly `publish`)
+- ALWAYS confirm with user before scheduling, showing the list of posts and their dates
+- If `create_content` fails for any entry, stop processing that entry, report the error, and keep the entry as `ready`
+- Verify the scheduled date is in the future before calling `create_content` -- if the date is in the past, report to user and skip
+
+---
+
+## Step 4: SYNC -- Synchronize WordPress status back to calendar
+
+**When to run:** User asks to "sync calendar" or "aggiorna stato calendario".
+
+**Procedure:**
+
+1. Read the current editorial calendar `.state.md` file.
+
+2. For each entry with a Post ID (status: `scheduled` or `published`):
+   a. Call `list_content` with the content type and filter by post ID:
+      ```
+      list_content:
+        content_type: {entry.Tipo}
+        search: {post_id}
+        per_page: 1
+      ```
+   b. Check the returned post status and update the calendar accordingly:
+      - If WP status = `publish` and calendar status = `scheduled` --> update to `published`
+      - If WP status = `future` --> keep as `scheduled`
+      - If WP status = `draft` --> note: post was reverted, update calendar to `draft`
+      - If WP status = `trash` --> note: post was deleted, report to user
+
+3. Recalculate `goals.posts_published` = count of entries with `status: published`.
+
+4. Write the updated calendar back to the `.state.md` file.
+
+5. Report to user:
+   ```
+   Sync calendario {calendar_id}:
+   - Post pubblicati: {posts_published}/{posts_target}
+   - Post schedulati: {scheduled_count}
+   - Post in lavorazione: {draft_count + ready_count}
+   - Slot da assegnare: {planned_count}
+   ```
+
+**Safety rules:**
+- NEVER modify WordPress post status during sync -- sync is read-only from WordPress
+- If a post was deleted or trashed, report to user but do not remove the calendar entry (mark with a note instead)
+
+---
+
+## Creating a Calendar Manually
+
+When the user wants to create a calendar without running the full PLAN step:
+
+1. Copy the structure from `references/editorial-schema.md`
+2. Fill in `site_id`, dates for each entry, and known titles
+3. Set `status: planned` for all entries
+4. Save as `.content-state/{YYYY-MM}-editorial.state.md`
+5. Then run the BRIEF step to generate brief files from the planned entries
+
+---
+
+## Safety Rules Summary
+
+- **ALWAYS** show the calendar and briefs to the user before writing any files
+- **ALWAYS** create WordPress posts as `status: future` (never `publish` directly)
+- **NEVER** overwrite existing briefs or calendar entries with higher status
+- **NEVER** modify WordPress posts during SYNC (read-only operation)
+- **ALWAYS** confirm with the user before scheduling posts to WordPress
+- **LOG** all scheduling actions in the calendar state file
+
+---
+
+## Known Limitations
+
+### AIWU MCP Server (cloud-based)
+
+The AIWU MCP server (`mcp__claude_ai_AIWU`) does **not** support the `post_date` field in `wp_create_post` or `wp_update_post`. This means `post_status: "future"` cannot be achieved through AIWU — WordPress auto-publishes the post when no future date is provided.
+
+**E2E test results (2026-03-02):**
+- `wp_create_post` with `post_status: "future"` → auto-published (no `post_date` parameter available)
+- `wp_update_post` with `post_date` + `post_status: "future"` from `draft` → auto-published (`post_date` not passed through)
+- `wp_update_post` on already-published post → `post_date` updated but status cannot revert from `publish` to `future`
+
+**Workaround:** Use the wp-rest-bridge MCP server's `create_content` tool, which natively supports the `date` parameter for scheduling future posts. AIWU can still be used for SYNC (read-only) and for content management tasks that don't require future scheduling.
+
+---
+
+## Reference Files
+
+- `references/editorial-schema.md` -- complete schema for editorial calendar `.state.md` files
+- `../wp-content-pipeline/references/content-brief-schema.md` -- brief file format and frontmatter fields
+- `../wp-content-pipeline/references/site-config-schema.md` -- site configuration defaults and cadence settings
+- `../wp-analytics/references/signals-feed-schema.md` -- signals feed format for topic suggestions
+
+---
+
+## Related Skills
+
+- **`wp-content-pipeline`** -- publishes briefs created by the BRIEF step through the full pipeline workflow
+- **`wp-analytics`** -- generates the signals feed consumed by the PLAN step for data-driven topic ideas
+- **`wp-content`** -- content creation and management (provides `create_content`, `list_content` MCP tools)
+- **`wp-social-email`** -- distribution channel scheduling (Buffer via `buf_create_update`, Mailchimp campaigns)
+- **`wp-content-repurposing`** -- multi-format adaptation for social distribution channels

package/skills/wp-editorial-planner/references/editorial-schema.md

@@ -0,0 +1,268 @@
+# Editorial Calendar Schema
+
+Schema reference for `{YYYY-MM}-editorial.state.md` files -- the monthly editorial calendar format used by the `wp-editorial-planner` skill to plan, track, and synchronize content across the publishing lifecycle.
+
+Each editorial calendar is a Markdown file with YAML frontmatter containing monthly goals and metadata, followed by weekly Markdown tables for content planning. Each table row represents a content entry that progresses through a five-stage status lifecycle and bridges to Phase 1 briefs (`.brief.md` files in the content pipeline) and Phase 2 signals (from the signals intelligence feed).
+
+---
+
+## File Format
+
+Each `{YYYY-MM}-editorial.state.md` file consists of:
+
+1. **YAML frontmatter** between `---` delimiters (monthly goals, metadata, SEO targets)
+2. **Markdown body** with weekly table sections, one per week of the month
+
+```
+---
+calendar_id: "CAL-2026-03"
+site_id: mysite
+# ... other fields ...
+---
+
+# Piano Editoriale — Marzo 2026
+
+## Settimana 1 (1-7 Mar)
+
+| Data | Titolo | Tipo | Status | Brief ID | Post ID | Canali |
+|------|--------|------|--------|----------|---------|--------|
+| Mar 4 | Article title here | post | planned | — | — | — |
+```
+
+---
+
+## Frontmatter Fields
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `calendar_id` | `string` | **Yes** | -- | Unique calendar identifier. Format: `CAL-YYYY-MM` |
+| `site_id` | `string` | **Yes** | -- | WordPress site identifier. Must match an existing `.content-state/{site_id}.config.md` |
+| `period` | `string` | **Yes** | -- | Date range the calendar covers. Format: `YYYY-MM-DD..YYYY-MM-DD` (month boundaries) |
+| `created` | `string` (ISO 8601) | **Yes** | -- | Date the calendar was first created |
+| `last_updated` | `string` (ISO 8601) | **Yes** | -- | Auto-updated on each modification |
+| `status` | `enum` | No | `active` | Calendar status: `active` \| `archived` |
+| `goals.posts_target` | `integer` | **Yes** | -- | Total posts planned for the month |
+| `goals.posts_published` | `integer` | No | `0` | Counter updated by SYNC step |
+| `goals.focus_topics` | `string[]` | No | `[]` | Topic clusters to prioritize this month |
+| `goals.seo_targets` | `object[]` | No | `[]` | Each object: `{keyword, target_position}` |
+
+### `goals.seo_targets` object fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `keyword` | `string` | **Yes** | Target keyword or keyphrase |
+| `target_position` | `string` | **Yes** | SERP target: `top-3`, `top-5`, `top-10`, `top-20` |
+
+---
+
+## Weekly Table Structure
+
+The body contains one `## Settimana N (date range)` section per week of the month. Each section contains a single Markdown table with 7 columns:
+
+| Column | Type | Description |
+|--------|------|-------------|
+| Data | `date` | Planned publication date. Format: `Mon DD` (e.g., `Mar 4`) |
+| Titolo | `string` | Content title, or `[da assegnare]` if not yet defined |
+| Tipo | `enum` | WordPress content type: `post` \| `page` \| `custom_type` |
+| Status | `enum` | Entry lifecycle status: `planned` \| `draft` \| `ready` \| `scheduled` \| `published` |
+| Brief ID | `string` | Reference to `.brief.md` file. Format: `BRF-YYYY-NNN`, or `—` if not yet created |
+| Post ID | `integer` | WordPress post ID after creation, or `—` if not yet created |
+| Canali | `string` | Comma-separated distribution channels (e.g., `linkedin, newsletter`), or `—` |
+
+**Notes:**
+- Each week section covers 7 calendar days
+- The final week of the month may extend beyond 7 days to cover the remaining days (e.g., `Settimana 4 (22-31 Mar)`)
+- Table headers must be repeated in every weekly section
+- The `—` character (em dash, U+2014) is used as the null/empty marker
+
+---
+
+## Entry Status Lifecycle
+
+Calendar entries progress through a linear five-stage lifecycle:
+
+```
+planned → draft → ready → scheduled → published
+```
+
+| Status | Description | Calendar state | Brief state |
+|--------|-------------|----------------|-------------|
+| `planned` | Slot reserved in the calendar. Title may be `[da assegnare]` | Entry exists in weekly table | No brief file yet |
+| `draft` | Title assigned, brief created | Title is final | Brief in `pipeline-active/` with `status: draft` |
+| `ready` | Brief content finalized, quality gates passed | No change | Brief in `pipeline-active/` with `status: ready` |
+| `scheduled` | WordPress post created with future publication date | Post ID populated | Brief `target.status: future` |
+| `published` | WordPress post is live, confirmed by SYNC step | Post ID present, status updated | Brief moves to `pipeline-archive/` |
+
+**Transition rules:**
+- `planned` -> `draft`: Requires a final title and Brief ID assignment
+- `draft` -> `ready`: Requires brief quality gates to pass (see `gates` block in content-brief-schema)
+- `ready` -> `scheduled`: Requires successful WordPress API call creating a post with `status: future`
+- `scheduled` -> `published`: Confirmed by the SYNC step when WordPress reports `post_status: publish`
+
+---
+
+## Integration with Phase 1 (Content Pipeline)
+
+The editorial calendar bridges directly to the content pipeline's brief system:
+
+- Each calendar entry with a Brief ID references a file at `.content-state/pipeline-active/BRF-YYYY-NNN.brief.md`
+- When the BRIEF step creates a new brief, it uses the site config defaults from `.content-state/{site_id}.config.md`
+- The brief's `target.scheduled_date` is set from the calendar entry's **Data** column
+- The brief's `distribution.channels` is set from the calendar entry's **Canali** column
+- When `wp-content-pipeline` archives a brief (`status: published`), the SYNC step updates the calendar entry accordingly
+
+### Data flow: Calendar -> Brief
+
+| Calendar column | Brief field | Notes |
+|-----------------|-------------|-------|
+| Data | `target.scheduled_date` | Converted to ISO 8601 with site default publish time |
+| Titolo | `content.title` | Exact match |
+| Tipo | `target.content_type` | Direct mapping |
+| Canali | `distribution.channels` | Comma-separated string parsed to array |
+| (site_id from frontmatter) | `target.site_id` | Inherited from calendar |
+
+---
+
+## Integration with Phase 2 (Signals Intelligence)
+
+The editorial calendar consumes signals intelligence data to inform content planning:
+
+- The PLAN step can read `.content-state/signals-feed.md` to suggest topics for `[da assegnare]` entries
+- Anomalies from the signals feed with action containing "content cluster opportunity" are prime candidates for planned entries
+- The `goals.focus_topics` field can be informed by high-scoring signal patterns
+
+### Signal-to-calendar workflow
+
+1. SCAN step generates `.content-state/signals-feed.md` with scored anomalies
+2. PLAN step reads the signals feed and identifies actionable opportunities
+3. Opportunities map to `[da assegnare]` slots in the current or next month's calendar
+4. When a topic is assigned, the entry title is updated and a `[da assegnare — topic da signals]` annotation may be used as an intermediate step
+
+---
+
+## Notes Section
+
+The body may end with a `# Note` section containing free-form editorial notes.
+
+Common uses:
+- **Newsletter aggregation rules**: How posts are grouped for newsletter distribution (e.g., biweekly digest)
+- **Distribution timing preferences**: When posts should be distributed on specific channels (e.g., LinkedIn at 09:00)
+- **Topic dependencies on signals data**: Which `[da assegnare]` slots depend on future signals analysis
+- **Cross-calendar references**: Links to related months or seasonal content plans
+- **Team coordination notes**: Reviewer assignments, approval deadlines
+
+---
+
+## File Naming Convention
+
+Editorial calendar files follow this naming pattern:
+
+```
+{YYYY-MM}-editorial.state.md
+```
+
+Examples:
+- `2026-03-editorial.state.md`
+- `2026-04-editorial.state.md`
+
+Files are stored in:
+- **Location**: `.content-state/` directory at the project root
+- **One file per month per site**: The `site_id` is stored in the frontmatter, not the filename
+- **Previous months**: Calendars for past months remain in `.content-state/` with `status: archived`
+- **Gitignored**: Calendar files are site-specific instance data and should be listed in `.gitignore`
+
+---
+
+## Example Calendar
+
+A complete `2026-03-editorial.state.md` for the mysite site:
+
+```markdown
+---
+calendar_id: "CAL-2026-03"
+site_id: mysite
+period: "2026-03-01..2026-03-31"
+created: "2026-02-28"
+last_updated: "2026-03-02"
+status: active
+
+goals:
+  posts_target: 8
+  posts_published: 2
+  focus_topics: [premium-water, sustainability, wellness]
+  seo_targets:
+    - keyword: "acqua premium"
+      target_position: top-5
+    - keyword: "bevanda zero calorie naturale"
+      target_position: top-10
+---
+
+# Piano Editoriale — Marzo 2026
+
+## Settimana 1 (1-7 Mar)
+
+| Data | Titolo | Tipo | Status | Brief ID | Post ID | Canali |
+|------|--------|------|--------|----------|---------|--------|
+| Mar 4 | Acqua premium: 5 benefici scientifici | post | published | BRF-2026-001 | 1234 | linkedin, newsletter |
+| Mar 6 | Come il frutto mediterraneo diventa bevanda | post | published | BRF-2026-002 | 1235 | linkedin, twitter |
+
+## Settimana 2 (8-14 Mar)
+
+| Data | Titolo | Tipo | Status | Brief ID | Post ID | Canali |
+|------|--------|------|--------|----------|---------|--------|
+| Mar 11 | Zero calorie, tutto gusto: la scienza | post | ready | BRF-2026-003 | — | linkedin, newsletter |
+| Mar 13 | Mediterraneo e sostenibilità: la filiera | post | draft | BRF-2026-004 | — | linkedin |
+
+## Settimana 3 (15-21 Mar)
+
+| Data | Titolo | Tipo | Status | Brief ID | Post ID | Canali |
+|------|--------|------|--------|----------|---------|--------|
+| Mar 18 | [da assegnare — topic da signals] | post | planned | — | — | — |
+| Mar 20 | [da assegnare] | post | planned | — | — | — |
+
+## Settimana 4 (22-31 Mar)
+
+| Data | Titolo | Tipo | Status | Brief ID | Post ID | Canali |
+|------|--------|------|--------|----------|---------|--------|
+| Mar 25 | [da assegnare] | post | planned | — | — | — |
+| Mar 27 | [da assegnare] | post | planned | — | — | — |
+
+# Note
+
+- Settimana 3-4: topic da definire basandosi su signals-feed.md del 15 marzo
+- Newsletter quindicinale: raccoglie i 4 post della quindicina precedente
+- LinkedIn: ogni post va distribuito il giorno stesso alle 09:00
+```
+
+---
+
+## Validation Rules
+
+The following rules are enforced when reading and writing editorial calendar files:
+
+### Format validations
+
+| Rule | Description |
+|------|-------------|
+| `calendar_id` format | Must follow `CAL-YYYY-MM` pattern (e.g., `CAL-2026-03`) |
+| `site_id` existence | Must match an existing `.content-state/{site_id}.config.md` file |
+| `period` span | Must span exactly one calendar month (`YYYY-MM-DD..YYYY-MM-DD`) |
+| Table columns | Each weekly table must have all 7 columns: Data, Titolo, Tipo, Status, Brief ID, Post ID, Canali |
+
+### Field validations
+
+| Rule | Description |
+|------|-------------|
+| `Status` values | Must be one of: `planned`, `draft`, `ready`, `scheduled`, `published` |
+| `Brief ID` format | Must follow `BRF-YYYY-NNN` pattern when present (not `—`) |
+| `Post ID` type | Must be a positive integer when present (not `—`) |
+
+### Consistency validations
+
+| Rule | Description |
+|------|-------------|
+| Published count | `goals.posts_published` must not exceed `goals.posts_target` |
+| Scheduled requires Post ID | Entries with `status: scheduled` must have a Post ID (not `—`) |
+| Published requires Post ID | Entries with `status: published` must have a Post ID (not `—`) |
+| Draft requires Brief ID | Entries with `status: draft` or higher must have a Brief ID (not `—`) |
+| Planned allows empty | Entries with `status: planned` may have `—` for Brief ID, Post ID, and Canali |

package/skills/wp-multilang-network/references/content-sync.md

@@ -109,17 +109,17 @@ When no multilingual plugin is used, sync content manually via MCP tools:
 ```bash
 # 1. Create content on primary site
 switch_site(site_id=1)  # Switch to English site
-create_content(type="post", title="Cactus Water Benefits", slug="cactus-water-benefits",
+create_content(type="post", title="Sparkling Water Benefits", slug="sparkling-water-benefits",
   content="...", status="publish")
 
 # 2. Replicate structure on Italian site
 switch_site(site_id=2)  # Switch to Italian site
-create_content(type="post", title="Benefici dell'Acqua di Cactus", slug="cactus-water-benefits",
+create_content(type="post", title="Benefici dell'Acqua Premium", slug="sparkling-water-benefits",
   content="[Italian translation]", status="draft")
 
 # 3. Replicate on German site
 switch_site(site_id=3)  # Switch to German site
-create_content(type="post", title="Vorteile von Kaktuswasser", slug="cactus-water-benefits",
+create_content(type="post", title="Vorteile von Kaktuswasser", slug="sparkling-water-benefits",
   content="[German translation]", status="draft")
 
 # 4. Switch back to primary